1<?xml version="1.0" encoding="UTF-8"?> 2 3<section id="syscalls"><title>System Calls</title> 4 5<para>The &posix-pac; module makes some system calls available from lisp. 6 Not all of these system calls are actually &posix;, so this package has a 7 nickname <quote role="package">OS</quote>. If the package prefix is 8 not specified below, the symbol resides in this package.</para> 9&base-module; 10<simpara>When this module is present, &features-my; 11 contains the symbol <constant>:SYSCALLS</constant>.</simpara> 12 13<section id="neworking"><title>Networking</title> 14<variablelist> 15 <varlistentry id="resolve-host"><term><code>(&resolve-host; 16 &optional-amp; &host-r;)</code></term> 17 <listitem><para>Returns the <type>HOSTENT</type> structure: 18 <variablelist><varlistentry><term><structfield>name</structfield></term> 19 <listitem><simpara>host name</simpara></listitem></varlistentry> 20 <varlistentry><term><structfield>aliases</structfield></term> 21 <listitem><simpara>&list-t; of aliases</simpara></listitem></varlistentry> 22 <varlistentry><term><structfield>addr-list</structfield></term> 23 <listitem><simpara>&list-t; of &ip; addresses as dotted quads (for IPv4) 24 or coloned octets (for IPv6)</simpara></listitem></varlistentry> 25 <varlistentry><term><structfield>addrtype</structfield></term> 26 <listitem><simpara>&integer-t; address type (IPv4 or IPv6) 27 </simpara></listitem></varlistentry></variablelist> 28 When &host-r; is omitted or &default-k;, return the data for the 29 current host. When &host-r; is &nil;, all the 30 host database is returned as a list (this would be the contents of the 31 <filename>/etc/hosts</filename> file on a &unix; system or 32 <filename>${windir}/system32/etc/hosts</filename> on a &win32; system). 33 </para><simpara>This is an interface 34 to <function role="unix">gethostent</function>, 35 <function role="bsd">gethostbyname</function>, 36 and <function role="bsd">gethostbyaddr</function>.</simpara> 37 </listitem></varlistentry> 38 <varlistentry id="service"><term><code>(OS:SERVICE &optional-amp; 39 <replaceable>service-name</replaceable> &proto-r;)</code></term> 40 <listitem><simpara>A convenience function for looking up a port given 41 the service name, such as <quote>WWW</quote> or <quote>FTP</quote>. 42 It returns the <type>SERVICE</type> structure 43 (name, list of aliases, port, protocol) for the given 44 <replaceable>service-name</replaceable> and &proto-r;, 45 or all services as a &list-t; if <replaceable>service-name</replaceable> 46 is missing or &nil;.</simpara><simpara>This is an interface 47 to <function role="unix">getservent</function>, 48 <function role="unix">getservbyname</function>, 49 and <function role="unix">getservbyport</function>.</simpara> 50</listitem></varlistentry></variablelist></section> 51 52<section id="file-system"><title>File system</title> 53<variablelist> 54 <varlistentry id="file-stat"><term><code>(POSIX:FILE-STAT 55 &path-r; &optional-amp; <replaceable>link-p</replaceable>)</code></term> 56 <listitem><para>Return the <type>FILE-STAT</type> structure. 57 &path-r; can be a &stream-t;, a &pathname-t;, a &string-t; or a 58 &number-t; (on a &unix; system, meaning &file-des;). 59 The first slot of the structure returned is the string or the 60 number on which <function role="unix">stat</function>, 61 &fstat;, 62 or <function role="unix">lstat</function> was called. 63 The other slots are numbers, members of the <type>struct stat</type>: 64 <variablelist> 65 <varlistentry><term><structfield>dev</structfield></term> 66 <listitem><simpara>Device ID of device containing file. 67 </simpara></listitem></varlistentry> 68 <varlistentry><term><structfield>ino</structfield></term> 69 <listitem><simpara>File serial number. 70 </simpara></listitem></varlistentry> 71 <varlistentry><term><structfield>mode</structfield></term> 72 <listitem><simpara>Mode of file. 73 </simpara></listitem></varlistentry> 74 <varlistentry><term><structfield>nlink</structfield></term> 75 <listitem><simpara>Number of hard links to the file. 76 </simpara></listitem></varlistentry> 77 <varlistentry><term><structfield>uid</structfield></term> 78 <listitem><simpara>User ID of file. 79 </simpara></listitem></varlistentry> 80 <varlistentry><term><structfield>gid</structfield></term> 81 <listitem><simpara>Group ID of file. 82 </simpara></listitem></varlistentry> 83 <varlistentry><term><structfield>rdev</structfield></term> 84 <listitem><simpara>Device ID (if file is character or block 85 special).</simpara></listitem></varlistentry> 86 <varlistentry><term><structfield>size</structfield></term> 87 <listitem><simpara>For regular files, the file size in bytes. 88 For symbolic links, the length in bytes of the pathname contained 89 in the symbolic link. 90 For a shared memory object, the length in bytes. 91 For a typed memory object, the length in bytes. 92 For other file types, the use of this field is unspecified. 93 </simpara></listitem></varlistentry> 94 <varlistentry><term><structfield>atime</structfield></term> 95 <listitem><simpara>&uni-time; of last access. 96 </simpara></listitem></varlistentry> 97 <varlistentry><term><structfield>mtime</structfield></term> 98 <listitem><simpara>&uni-time; of last data modification. 99 </simpara></listitem></varlistentry> 100 <varlistentry><term><structfield>ctime</structfield></term> 101 <listitem><simpara>&uni-time; of last status change 102 (on &win32; - creation time).</simpara></listitem></varlistentry> 103 <varlistentry><term><structfield>blksize</structfield></term> 104 <listitem><simpara>A file system-specific preferred I/O block size 105 for this object. In some file system types, this may vary from 106 file to file.</simpara></listitem></varlistentry> 107 <varlistentry><term><structfield>blocks</structfield></term> 108 <listitem><simpara>Number of blocks allocated for this object. 109 </simpara></listitem></varlistentry></variablelist> 110 All slots are read-only.</para> 111 <simpara>If the system does not support a particular field (e.g., 112 &win32; prior to 2000 does not have hard links), &nil; (or the 113 default, like 1 for the number of hard links for old &win32;) is 114 returned.</simpara> 115 <note><title>&win32-only;</title> 116 <para>Normally, one would expect <code>(POSIX:FILE-STAT 117 "foo")</code> and <code>(POSIX:FILE-STAT (&open; "foo"))</code> to 118 return <quote>similar</quote> objects (&open;ing a file changes its 119 access time though). This is ¬-e; the case on &win32;, where 120 <function role="unix">stat</function> works but &fstat; does ¬-e;. 121 Specifically, &fstat; requires an &int-t; argument of an unknown 122 nature, and it is not clear how do deduce it from the &win32; file handle. 123 Therefore, instead of always failing on open &file-stream-t; arguments, 124 this function calls 125 <function role="win32">GetFileInformationByHandle</function> and 126 fills the <type>FILE-STAT</type> return value based on that. 127 </para></note></listitem></varlistentry> 128 <varlistentry id="set-file-stat"><term><code>(POSIX:SET-FILE-STAT 129 &path-r; &key-amp; :ATIME :MTIME :MODE :UID :GID)</code></term> 130 <listitem><simpara>Set some file attributes using 131 <function role="unix">chmod</function>, 132 <function role="unix">chown</function>, 133 and <function role="unix">utime</function>. 134 </simpara></listitem></varlistentry> 135 <varlistentry id="stat-vfs"><term><code>(POSIX:STAT-VFS &path-r;)</code></term> 136 <listitem><para>Return a <type>STAT-VFS</type> structure. 137 &path-r; can be a &stream-t;, a &pathname-t;, a &string-t; or a 138 &number-t; (on a &unix; system, meaning &file-des;). 139 The first slot of the structure returned is the string 140 or the number on which <function role="unix">statvfs</function> or 141 <function role="unix">fstatvfs</function> was called. 142 The other slots are members of the <type>struct statvfs</type>: 143 <variablelist> 144 <varlistentry><term><structfield>bsize</structfield></term> 145 <listitem><simpara>File system block size. 146 </simpara></listitem></varlistentry> 147 <varlistentry><term><structfield>frsize</structfield></term> 148 <listitem><simpara>Fundamental file system block size. 149 </simpara></listitem></varlistentry> 150 <varlistentry><term><structfield>blocks</structfield></term> 151 <listitem><simpara>Total number of blocks on file system in units of 152 <structfield>frsize</structfield>.</simpara></listitem></varlistentry> 153 <varlistentry><term><structfield>bfree</structfield></term> 154 <listitem><simpara>Total number of free blocks. 155 </simpara></listitem></varlistentry> 156 <varlistentry><term><structfield>bavail</structfield></term> 157 <listitem><simpara>Number of free blocks available to 158 non-privileged processes.</simpara></listitem></varlistentry> 159 <varlistentry><term><structfield>files</structfield></term> 160 <listitem><simpara>Total number of file serial numbers. 161 </simpara></listitem></varlistentry> 162 <varlistentry><term><structfield>ffree</structfield></term> 163 <listitem><simpara>Total number of free file serial numbers. 164 </simpara></listitem></varlistentry> 165 <varlistentry><term><structfield>favail</structfield></term> 166 <listitem><simpara>Number of file serial numbers available to 167 non-privileged processes.</simpara></listitem></varlistentry> 168 <varlistentry><term><structfield>fsid</structfield></term> 169 <listitem><simpara>File system ID.</simpara></listitem></varlistentry> 170 <varlistentry><term><structfield>flag</structfield></term> 171 <listitem><simpara>List of platform-dependent values, such as &ro-k;. 172 </simpara></listitem></varlistentry> 173 <varlistentry><term><structfield>namemax</structfield></term> 174 <listitem><simpara>Maximum filename length. 175 </simpara></listitem></varlistentry> 176 <varlistentry><term><structfield>vol-name</structfield></term> 177 <listitem><simpara>Volume name (&win32; only). 178 </simpara></listitem></varlistentry> 179 <varlistentry><term><structfield>fs-type</structfield></term> 180 <listitem><simpara>File system type (&win32; only). 181 </simpara></listitem></varlistentry></variablelist> 182 All slots are read-only. 183 </para></listitem></varlistentry> 184 <varlistentry id="chroot"><term><code>(POSIX:CHROOT &path-r;)</code></term> 185 <listitem><simpara>Change the apparent disk root directory for the current 186 running process (and its children) using 187 <function role="bsd">chroot</function>.</simpara> 188 <simpara>Unless the process has superuser privileges, the operation will 189 probably fail with <constant role="errno">EPERM</constant>.</simpara> 190 </listitem></varlistentry> 191 <varlistentry id="file-tree-walk"><term><code>(POSIX:FILE-TREE-WALK &path-r; 192 &func-r; &key-amp; FD-LIMIT CHDIR DEPTH MOUNT PHYS)</code></term> 193 <listitem><para>For each object under &path-r; calls &func-r; with 5 194 arguments: <orderedlist> 195 <listitem><simpara>the pathname of the object</simpara></listitem> 196 <listitem><simpara>the <type>FILE-STAT</type> instance containing 197 information on the object (or &nil;, see below)</simpara></listitem> 198 <listitem><para>a keyword giving additional information. 199 Its value is one of the following:<variablelist> 200 <varlistentry><term><constant>:F</constant></term> 201 <listitem><simpara>The object is a file. 202 </simpara></listitem></varlistentry> 203 <varlistentry><term><constant>:D</constant></term> 204 <listitem><simpara>The object is a directory. 205 </simpara></listitem></varlistentry> 206 <varlistentry><term><constant>:DP</constant></term> 207 <listitem><simpara>The object is a directory and subdirectories have 208 been visited. (This condition shall only occur if the 209 <constant>:DEPTH</constant> argument is non-&nil;.) 210 </simpara></listitem></varlistentry> 211 <varlistentry><term><constant>:SL</constant></term> 212 <listitem><simpara>The object is a symbolic link. (This condition shall 213 only occur if the <constant>PHYS</constant> argument is non-&nil;.) 214 </simpara></listitem></varlistentry> 215 <varlistentry><term><constant>:SLN</constant></term> 216 <listitem><simpara>The object is a symbolic link that does not name an 217 existing file. (This condition shall only occur if the 218 <constant>PHYS</constant> argument is &nil;.) 219 </simpara></listitem></varlistentry> 220 <varlistentry><term><constant>:DNR</constant></term> 221 <listitem><simpara>The object is a directory that cannot be read. 222 The fn function shall not be called for any of its descendants. 223 </simpara></listitem></varlistentry> 224 <varlistentry><term><constant>:NS</constant></term> 225 <listitem><simpara> The <function role="unix">stat</function> function 226 failed on the object because of lack of appropriate permission. 227 The <type>FILE-STAT</type> argument is &nil;. 228 If <function role="unix">stat</function> fails for any other reason, 229 and &err-sig;.</simpara></listitem></varlistentry></variablelist> 230 </para></listitem> 231 <listitem><simpara>the offset of the object's filename in the pathname 232 passed as the first argument to &func-r;.</simpara></listitem> 233 <listitem><simpara>the depth relative to the root of the walk, 234 where the root level is 0.</simpara></listitem></orderedlist></para> 235 <simpara>As soon as &func-r; returns non-&nil;, this function returns that 236 value; if &func-r; always returns &nil;, then this function also returns 237 &nil; when the file tree is exhausted.</simpara> 238 <simpara>The <constant>:FD-LIMIT</constant> argument defaults to 5.</simpara> 239 <simpara>If <constant>:CHDIR</constant> argument is non-&nil;, the function 240 shall change the current working directory to each directory as it reports 241 files in that directory</simpara> 242 <simpara>If <constant>:DEPTH</constant> argument is non-&nil;, the function 243 shall report all files in a directory before reporting the directory 244 itself.</simpara> 245 <simpara>If <constant>:MOUNT</constant> argument is non-&nil;, the function 246 shall only report files in the same file system as &path-r;.</simpara> 247 <simpara>If <constant>:PHYS</constant> argument is non-&nil;, the function 248 shall perform a physical walk and shall not follow symbolic links.</simpara> 249 <simpara>Calls <function role="unix">nftw</function>.</simpara> 250 </listitem></varlistentry> 251 <varlistentry id="file-info"><term><code>(OS:FILE-INFO &path-r; 252 &optional-amp; all)</code></term> 253 <listitem><para>Return the <type>FILE-INFO</type> structure. 254 &path-r; should be a &path-des;. The 7 slots are<simplelist columns="1"> 255 <member><structfield>attributes</structfield></member> 256 <member><structfield>ctime</structfield></member> 257 <member><structfield>atime</structfield></member> 258 <member><structfield>wtime</structfield></member> 259 <member><structfield>size</structfield></member> 260 <member><structfield>name</structfield></member> 261 <member><structfield>name-short</structfield></member> 262 </simplelist>When &path-r; is wild, returns just the first match, 263 unless the second (optional) argument is non-&nil;, in which case a 264 &list-t; of objects is returned, one for each match. 265 </para></listitem></varlistentry> 266 <varlistentry id="stream-lock"><term><code>(POSIX:STREAM-LOCK &stream-r; 267 <replaceable>lock-p</replaceable> &key-amp; 268 (:BLOCK &t;) (:SHARED &nil;) (:START 0) (:END &nil;))</code></term> 269 <listitem><simpara>Set or remove a file lock for the (portion of the) 270 file associated with &stream-r;, 271 depending on <replaceable>lock-p</replaceable>. 272 When <replaceable>block</replaceable> is &nil;, the call is non-blocking, 273 and when locking fails, it returns &nil;. 274 When <replaceable>shared</replaceable> is non-&nil;, 275 then lock can be shared between several callers. 276 Several processes can set a <replaceable>shared</replaceable> 277 (i.e., <emphasis>read</emphasis>) lock, but only one can set 278 an <replaceable>exclusive</replaceable> (i.e., <emphasis>write</emphasis>, 279 or non-<replaceable>shared</replaceable>) lock. 280 Uses <function role="unix">fcntl</function> 281 or <function role="win32">LockFileEx</function>.</simpara> 282 <warning><simpara>&unix; and &win32; differ on locking 0-length files: on 283 &win32;, two processes can have exclusive locks on it!</simpara></warning> 284 <warning><simpara>&win32; locks are <emphasis>mandatory</emphasis>: 285 if you lock a file, others will not be able to open it!</simpara> 286 <simpara>&unix; locks are usually <emphasis>advisory</emphasis>: a process 287 is free to ignore it, but on some &unix; systems one can mount some 288 file system with <emphasis>mandatory</emphasis> locks.</simpara></warning> 289 </listitem></varlistentry> 290 <varlistentry id="with-stream-lock"><term><code>(POSIX:WITH-STREAM-LOCK 291 (&stream-r; &rest-amp; &options-r;) &body-amp; &body-r;)</code></term> 292 <listitem><simpara>Lock the &stream-r;, execute the &body-r;, unlock 293 the &stream-r;. Pass &options-r; to &stream-lock;. 294 </simpara></listitem></varlistentry> 295 <varlistentry id="fcntl"><term><code>(&stream-options; 296 &stream-r; &command-r; &optional-amp; &value-r;)</code></term> 297 <listitem><simpara>Call <function role="unix">fcntl</function>, 298 &command-r; can be <constant>:FD</constant> or <constant>:FL</constant>. 299 </simpara><simpara>When &value-r; is missing, the option is queried and 300 the value is returned; if &value-r; is supplied, the option is set and 301 no values are returned.</simpara></listitem></varlistentry> 302 <varlistentry id="file-size"><term><code>(&file-size; &file-r;)</code></term> 303 <term><code>(&setf; (&file-size; &file-r;) &size-r;)</code></term> 304 <listitem><simpara>Extend &file-length; to operate on &path-des;s.</simpara> 305 <simpara>Set the &size-r; of a &file-r; using 306 <function role="unix">ftruncate</function> (if &file-r; is an open 307 &file-stream-t;) or <function role="unix">truncate</function> (if 308 &file-r; is a &path-des;).</simpara> 309 <simpara>Use <function role="win32">SetFilePointerEx</function> 310 and <function role="win32">SetEndOfFile</function> on &win32;. 311 </simpara></listitem></varlistentry> 312 <varlistentry id="mknod"><term><code>(POSIX:MKNOD &path-r; &type-r; 313 &mode-r;)</code></term> 314 <listitem><simpara>Create a special file using 315 <function role="unix">mknod</function>. 316 Use <constant>:FIFO</constant> to create pipes 317 and <constant>:SOCK</constant> to create sockets. 318 </simpara></listitem></varlistentry> 319 <varlistentry id="convert-mode"> 320 <term><code>(POSIX:CONVERT-MODE &mode-r;)</code></term> 321 <listitem><simpara>Convert between numeric, (e.g., <literal>0644</literal>) 322 and symbolic (e.g., <literal role="data">(:RUSR :WUSR :RGRP 323 :ROTH)</literal>) file modes.</simpara></listitem></varlistentry> 324 <varlistentry id="umask"><term><code>(POSIX:UMASK &mode-r;)</code></term> 325 <listitem><simpara>Change process mask using 326 <function role="unix">umask</function>. 327 </simpara></listitem></varlistentry> 328 <varlistentry id="copy-file"><term><code>(©-file; &source-r; &dest-r; 329 &key-amp; :METHOD :PRESERVE :IF-EXISTS :IF-DOES-NOT-EXIST)</code></term> 330 <listitem><simpara>This is an interface to 331 <function role="unix">symlink</function> 332 (when &method-r; is <constant>:SYMLINK</constant>), 333 <function role="unix">link</function> 334 (when it is <constant>:HARDLINK</constant>), 335 and <function role="unix">rename</function> 336 (when it is <constant>:RENAME</constant>) system calls, as well as, 337 you guessed it, a generic file copy utility (when &method-r; is ©-k;). 338 </simpara><simpara>When &method-r; is <constant>:HARDLINK-OR-COPY</constant> 339 and <function role="unix">link</function> fails (e.g., because the 340 &source-r; and &dest-r; are on different devices), fall back to ©-k;. 341 </simpara><simpara>Both &source-r; and &dest-r; may be wild, in which 342 case &translate-pathname; is used.</simpara> 343 <simpara>When <replaceable>preserve</replaceable> is non-&nil;, try 344 to duplicate the time, owner, and permission characteristics of each 345 source file in the corresponding destination file, 346 similar to <command role="unix">cp -p</command>.</simpara> 347 <simpara>The meaning and defaults of &if-exists; and 348 &if-does-not-exist; are the same as in &open;.</simpara> 349 <simpara>The actual &dest-r; file created is 350 <code>(&merge-pathnames; &source-r; &dest-r;)</code> so that 351 <code>(©-file; "foo" "dir/")</code> creates 352 <filename>"dir/foo"</filename> and 353 <code>(©-file; "foo.csv" "bar")</code> creates 354 <filename>"bar.csv"</filename>. 355 If you want to actually copy <filename>"foo.csv"</filename> to 356 <filename>"bar"</filename>, do 357 <code>(©-file; (&make-pathname; :name "foo.csv") "bar")</code>. 358 </simpara></listitem></varlistentry> 359 <varlistentry id="dup-handle"><term><code>(&dup-handle; 360 <replaceable>fd1</replaceable> &optional-amp; 361 <replaceable>fd2</replaceable>)</code></term> 362 <listitem><simpara>This is an interface to the &dup; system calls on 363 &unix; systems and to <function role="win32">DuplicateHandle</function> 364 system call on &win32;.</simpara></listitem></varlistentry> 365 <varlistentry id="shortcut-info"><term><code>(OS:SHORTCUT-INFO 366 &path-r;)</code></term> 367 <listitem><simpara>Return information about a &win32; shortcut 368 (<filename>#P".lnk"</filename>) file contents in a 369 <type>SHORTCUT-INFO</type> structure.</simpara></listitem></varlistentry> 370 <varlistentry id="make-shortcut"><term><code>(OS:MAKE-SHORTCUT &path-r; 371 &key-amp; :WORKING-DIRECTORY :ARGUMENTS :SHOW-COMMAND :ICON :DESCRIPTION 372 :HOT-KEY :PATH)</code></term> 373 <listitem><simpara>Create (or modify the properties of an existing one) 374 a &win32; shortcut (<filename>#P".lnk"</filename>) file. 375 </simpara></listitem></varlistentry> 376 <varlistentry id="file-properties"><term><code>(OS:FILE-PROPERTIES 377 filename set &key-amp; :INITID &allow-other-keys-amp;)</code></term> 378 <listitem><para>Wrapper for the &win32; 379 <function role="win32">IPropertyStorage</function> functionality. 380 <variablelist><varlistentry><term>&filename-r;</term> 381 <listitem><simpara>name of a compound file (where properties are stored) 382 or (on NTFS) name of any file (properties are stored in the filesystem). 383 For compound files on NTFS, file storage is preferred. 384 </simpara></listitem></varlistentry> 385 <varlistentry><term><replaceable>set</replaceable></term> 386 <listitem><simpara>property set, either <constant>:BUILT-IN</constant> 387 or <constant>:USER-DEFINED</constant> 388 </simpara></listitem></varlistentry> 389 <varlistentry><term><constant>:INITID</constant> 390 <replaceable>init-id</replaceable></term> 391 <listitem><simpara>set the <replaceable>init-id</replaceable> 392 </simpara></listitem></varlistentry> 393 <varlistentry><term><replaceable>specifier value</replaceable></term> 394 <listitem><para><variablelist> 395 <varlistentry><term><replaceable>specifier</replaceable></term> 396 <listitem><para>the property specifier: an &integer-t;, 397 &keyword-t;, &string-t; or a &list-t; of an &integer-t; or a 398 &keyword-t; and a &string-t;. 399 <variablelist><varlistentry><term>&integer-t;</term> 400 <listitem><simpara>a property identifier 401 </simpara></listitem></varlistentry> 402 <varlistentry><term>&keyword-t;</term> 403 <listitem><para>Predefined &keyword-t; IDs are 404 <simplelist columns="4"> 405 <member><constant>:APPNAME</constant></member> 406 <member><constant>:AUTHOR</constant></member> 407 <member><constant>:CHARCOUNT</constant></member> 408 <member><constant>:CODEPAGE</constant></member> 409 <member><constant>:COMMENTS</constant></member> 410 <member><constant>:CREATE-DTM</constant></member> 411 <member><constant>:DOC-SECURITY</constant></member> 412 <member><constant>:EDITTIME</constant></member> 413 <member><constant>:KEYWORDS</constant></member> 414 <member><constant>:LASTAUTHOR</constant></member> 415 <member><constant>:LASTPRINTED</constant></member> 416 <member><constant>:LASTSAVE-DTM</constant></member> 417 <member><constant>:LOCALE</constant></member> 418 <member><constant>:PAGECOUNT</constant></member> 419 <member><constant>:REVNUMBER</constant></member> 420 <member><constant>:SUBJECT</constant></member> 421 <member><constant>:TEMPLATE</constant></member> 422 <member><constant>:THUMBNAIL</constant></member> 423 <member><constant>:TITLE</constant></member> 424 <member><constant>:WORDCOUNT</constant></member> 425 </simplelist></para></listitem></varlistentry> 426 <varlistentry><term>&string-t;</term> 427 <listitem><simpara>string property specifier. 428 If no match is found, the first ID >= init-id 429 (which defaults to 2) is associated with the 430 string and its value is replaced with new value. 431 </simpara></listitem></varlistentry> 432 <varlistentry><term>(&integer-t;|&keyword-t; 433 &string-t;)</term> 434 <listitem><simpara>the first element is used as 435 a specifier, the string is associated with this ID. 436 </simpara></listitem></varlistentry></variablelist> 437 </para></listitem></varlistentry> 438 <varlistentry><term>&value-r;</term> 439 <listitem><para>the new value of the property, a suitable Lisp 440 object, &nil; or a &list-t; of a &keyword-t; and the value 441 itself. If &value-r; is &nil;, no assignment is done. 442 <constant>:EMPTY</constant> and <constant>:NULL</constant> 443 correspond to the <type>VT_EMPTY</type> 444 and <type>VT_NULL</type> data types. 445 &keyword-t; in the &list-t; specifies the desired type of 446 the property being set. 447 Supported types are<simplelist columns="4"> 448 <member><constant>:BOOL</constant></member> 449 <member><constant>:BSTR</constant></member> 450 <member><constant>:DATE</constant></member> 451 <member>&error-k;</member> 452 <member><constant>:FILETIME</constant></member> 453 <member><constant>:I1</constant></member> 454 <member><constant>:I2</constant></member> 455 <member><constant>:I4</constant></member> 456 <member><constant>:I8</constant></member> 457 <member><constant>:LPSTR</constant></member> 458 <member><constant>:LPWSTR</constant></member> 459 <member><constant>:R4</constant></member> 460 <member><constant>:R8</constant></member> 461 <member><constant>:UI1</constant></member> 462 <member><constant>:UI2</constant></member> 463 <member><constant>:UI4</constant></member> 464 <member><constant>:UI8</constant></member> 465 <member><constant>:UINT</constant></member></simplelist> 466 <type>FILETIME</type>s are converted to/from the universal 467 time format, while <type>DATE</type>s are not. 468 </para></listitem></varlistentry></variablelist> 469 </para></listitem></varlistentry></variablelist> 470 Returns the property contents before assignment as multiple values. 471 </para></listitem></varlistentry> 472 <varlistentry id="file-owner"><term><code>(OS:FILE-OWNER 473 &filename-r;)</code></term> 474 <listitem><simpara>Return the owner of the file.</simpara> 475 <simpara>&unix-w32-only;</simpara></listitem></varlistentry> 476 <varlistentry id="mkstemp"><term><code>(POSIX:MKSTEMP &filename-r; 477 &key-amp; &direction-k; &eltype; &extfmt; &buffered;)</code></term> 478 <listitem><simpara>Calls <function role="unix">mkstemp</function>; 479 returns a &file-stream-t;.</simpara> 480 <simpara>&direction-k; should allow output.</simpara> 481 </listitem></varlistentry> 482 <varlistentry id="mkdtemp"><term><code>(POSIX:MKDTEMP 483 &filename-r;)</code></term> 484 <listitem><simpara>Calls <function role="unix">mkdtemp</function>; 485 creates a new empty temporary directory and returns its namestring. 486 </simpara></listitem></varlistentry> 487 <varlistentry id="sync"><term><code>(POSIX:SYNC &optional-amp; 488 &stream-r;)</code></term> 489 <listitem><simpara>Calls <function role="unix">fsync</function> 490 (<function role="win32">FlushFileBuffers</function> on &win32;) 491 on the &file-des; associated with &stream-r;, 492 or <function role="unix">sync</function> 493 when &stream-r; is not supplied</simpara></listitem></varlistentry> 494</variablelist></section> 495 496<section id="user-group"><title>Users and Groups</title> 497<variablelist> 498 <varlistentry id="user-info"><term><code>(POSIX:USER-INFO 499 &optional-amp; &user-r;)</code></term> 500 <listitem><simpara>Return the <type>USER-INFO</type> structure (name, 501 encoded password, UID, GID, full name, home directory, shell). 502 &user-r; should be a &string-t; 503 (<function role="unix">getpwnam</function> is used) or an &integer-t; 504 (<function role="unix">getpwuid</function> is used). 505 When &user-r; is missing or &nil;, return all 506 users (using <function role="unix">getpwent</function>). 507 When &user-r; is &default-k;, return the information about the current user 508 (using <function role="unix">getlogin</function>).</simpara> 509 <simpara>&unix-only;</simpara></listitem></varlistentry> 510<varlistentry id="group-info"><term><code>(POSIX:GROUP-INFO 511 &optional-amp; <replaceable>group</replaceable>)</code></term> 512 <listitem><simpara>Return the <type>GROUP-INFO</type> structure (name, 513 GID, member &list-t;). <replaceable>group</replaceable> should be a 514 &string-t; (<function role="unix">getgrnam</function> is used) or an 515 &integer-t; (<function role="unix">getgrgid</function> is used). 516 When <replaceable>group</replaceable> is missing or &nil;, return all 517 groups (using <function role="unix">getgrent</function>).</simpara> 518 <simpara>&unix-only;</simpara></listitem></varlistentry> 519<varlistentry id="user-shells"><term><code>(POSIX:USER-SHELLS)</code></term> 520 <listitem><simpara>Call <function role="bsd">getusershell</function>. 521</simpara></listitem></varlistentry> 522<varlistentry id="get-user-sid"><term><code>(OS:GET-USER-SID 523 &optional-amp; &user-r;)</code></term> 524 <listitem><simpara>Call <function role="win32">LookupAccountName</function> 525 on &user-r; or, if that is not supplied, call 526 <function role="win32">OpenProcessToken</function>, 527 <function role="win32">GetTokenInformation</function>, and then 528 <function role="win32">ConvertSidToStringSid</function> on 529 <structfield>User.Sid</structfield>.</simpara></listitem></varlistentry> 530</variablelist></section> 531 532<section id="sysinfo"><title>System Information</title> 533<variablelist> 534 <varlistentry id="uname"><term><code>(POSIX:UNAME)</code></term> 535 <listitem><simpara>Return a structure describing the OS, derived from 536 <function role="unix">uname</function>.</simpara></listitem></varlistentry> 537 <varlistentry id="sysconf"> 538 <term><code>(POSIX:SYSCONF &optional-amp; &what-r;)</code></term> 539 <term><code>(POSIX:CONFSTR &optional-amp; &what-r;)</code></term> 540 <listitem><simpara>Return the specified configuration parameter or a 541 &plist; of all available parameters (when &what-r; is missing or 542 &nil;), by calling <function role="unix">sysconf</function> 543 and <function role="unix">confstr</function> respectively. 544 </simpara></listitem></varlistentry> 545 <varlistentry id="pathconf"><term><code>(POSIX:PATHCONF &path-r; 546 &optional-amp; &what-r;)</code></term> 547 <listitem><simpara>Return the specified configuration parameter or a 548 &plist; of all available parameters (when &what-r; is missing or 549 &nil;), by calling <function role="unix">fpathconf</function> on 550 open file streams and <function role="unix">pathconf</function> on 551 all other &path-des;s.</simpara></listitem></varlistentry> 552 <varlistentry id="rlimit"><term><code>(&rlimit; 553 &optional-amp; &what-r;)</code></term> 554 <listitem><simpara>Return the current and the maximal limits as two 555 values when &what-r; is specified or the &plist; of all available 556 limits (as an <type>RLIMIT</type> structure) when &what-r; is 557 missing or &nil;, by calling <function role="unix">getrlimit</function>. 558 </simpara></listitem></varlistentry> 559 <varlistentry id="set-rlimit"><term><code>(&setf; (&rlimit; &what-r;) 560 (&values; <replaceable>cur</replaceable> 561 <replaceable>max</replaceable>))</code></term> 562 <term><code>(&setf; (&rlimit; &what-r;) 563 <replaceable>rlimit</replaceable>)</code></term> 564 <term><code>(&setf; (&rlimit;) 565 <replaceable>rlimit-plist</replaceable>)</code></term> 566 <listitem><para>Set the limits using 567 <function role="unix">setrlimit</function>.<orderedlist> 568 <listitem><simpara>In the first form, <replaceable>cur</replaceable> 569 and <replaceable>max</replaceable> are numbers 570 (or &nil; for <constant>RLIM_INFINITY</constant>).</simpara></listitem> 571 <listitem><simpara>In the second form, <replaceable>rlimit</replaceable> 572 is an <type>RLIMIT</type> structure.</simpara></listitem> 573 <listitem><simpara>In the third form, 574 <replaceable>rlimit-plist</replaceable> is a &plist;, as returned by 575 <code>(&rlimit;)</code>.</simpara></listitem> 576 </orderedlist></para></listitem></varlistentry> 577 <varlistentry id="usage"><term><code>(&usage; 578 &optional-amp; &what-r;)</code></term> 579 <listitem><simpara>Return the <type>USAGE</type> structure describing the 580 resource usage of the thread, process, or its children, using 581 <function role="unix">getrusage</function>. WHen &what-r; is missing 582 or &nil;, return all available data as a &plist;. 583 </simpara></listitem></varlistentry> 584 <varlistentry id="bogomips"><term><code>(POSIX:BOGOMIPS)</code></term> 585 <listitem><simpara>Compute the 586 <ulink url="http://en.wikipedia.org/wiki/BogoMips">BogoMips</ulink> 587 rating.</simpara></listitem></varlistentry> 588 <varlistentry id="loadavg"><term><code>(POSIX:LOADAVG &optional-amp; 589 percentp)</code></term> 590 <listitem><simpara>Return 1, 5, and 15 minute system load averages, 591 retrieved by <function role="bsd">getloadavg</function>. 592 If the argument is specified and non-&nil;, the values are returned 593 as integer percentiles.</simpara></listitem></varlistentry> 594 <varlistentry><term><code>(OS:SYSTEM-INFO)</code></term> 595 <listitem><simpara>Return &win32; system information in a 596 <type>SYSTEM-INFO</type> structure.</simpara></listitem></varlistentry> 597 <varlistentry><term><code>(OS:VERSION)</code></term> 598 <listitem><simpara>Return &win32; version information in a 599 <type>VERSION</type> structure.</simpara></listitem></varlistentry> 600 <varlistentry><term><code>(OS:MEMORY-STATUS)</code></term> 601 <listitem><simpara>Return &win32; memory status information in a 602 <type>MEMORY-STATUS</type> structure.</simpara></listitem></varlistentry> 603 <varlistentry id="phys-mem"><term><code>(OS:PHYSICAL-MEMORY)</code></term> 604 <listitem><simpara>Return 2 values: total and available physical memory. 605 </simpara><simpara>&unix-w32-only;</simpara></listitem></varlistentry> 606 <varlistentry id="hostid"><term><code>(OS:HOSTID)</code></term> 607 <term><code>(&setf; (OS:HOSTID) &value-r;)</code></term> 608 <listitem><simpara>Call <function role="unix">gethostid</function> and 609 return a (hopefully) universally unique &integer-t; identifier of 610 this machine.</simpara> 611 <warning><para>On &linux; this number appears to be the IPv4 32-bit 612 address with the first 2 bytes and the last 2 bytes swapped: 613<programlisting language="lisp">(&convert-address; :inet (os:hostid)) 614<computeroutput>"7.3.192.168"</computeroutput> 615(first (posix:hostent-addr-list (&resolve-host; :default))) 616<computeroutput>"192.168.7.3"</computeroutput></programlisting>This, of 617course, means that <quote>universally unique</quote> it is ¬-e;. 618 </para></warning><simpara>Superuser can also set host identifier 619 using &setf; which calls <function role="bsd">sethostid</function>. 620 </simpara><simpara>&unix-w32-only;</simpara></listitem></varlistentry> 621 <varlistentry id="domainname"><term><code>(OS:DOMAINNAME)</code></term> 622 <term><code>(&setf; (OS:DOMAINNAME) &dom-r;)</code></term> 623 <listitem><simpara>Call <function role="bsd">getdomainname</function> 624 and <function role="bsd">setdomainname</function>.</simpara></listitem> 625</varlistentry></variablelist></section> 626 627<section id="posix-math"><title>Mathematical functions</title> 628<para>We implement access to <simplelist columns="1"> 629 <member><code>(<function role="unix">erf</function> &real-r;)</code></member> 630 <member><code>(<function role="unix">erfc</function> &real-r;)</code></member> 631 <member><code>(<function role="unix">j0</function> &real-r;)</code></member> 632 <member><code>(<function role="unix">j1</function> &real-r;)</code></member> 633 <member><code>(<function role="unix">jn</function> &int-r; 634 &real-r;)</code></member> 635 <member><code>(<function role="unix">y0</function> &real-r;)</code></member> 636 <member><code>(<function role="unix">y1</function> &real-r;)</code></member> 637 <member><code>(<function role="unix">yn</function> &int-r; 638 &real-r;)</code></member> 639 <member><code>(<function role="unix">tgamma</function> 640 &real-r;)</code></member> 641 <member><code>(<function role="unix">lgamma</function> 642 &real-r;)</code></member></simplelist> 643which compute the error functions, Bessel functions and Gamma.</para> 644<simpara>These functions are required by the &posix; standard and should 645 be declared in <filename role="unix">math.h</filename>.</simpara> 646<warning><simpara>Please note that these functions do ¬-e; provide 647 lisp-style error handling and precision, and do all the computations 648 at the &double-float-t; level.</simpara></warning> 649<para>Function <code>(<function role="unix">ffs</function> &n-r;)</code> 650 finds the first bit set. It is implemented in pure Lisp and supports 651 &bignum-t;s.</para> 652</section> 653 654<section id="encryption"><title>Encryption</title> 655<variablelist> 656 <varlistentry id="crypt"><term><code>(POSIX:CRYPT &key-r; 657 <replaceable>salt</replaceable>)</code></term> 658 <listitem><simpara>Call <function role="unix">crypt</function>, 659 arguments are &string-t;s.</simpara></listitem></varlistentry> 660 <varlistentry id="encrypt"> 661 <term><code>(POSIX:ENCRYPT <replaceable>block</replaceable> 662 <replaceable>decrypt-p</replaceable>)</code></term> 663 <term><code>(POSIX:SETKEY &key-r;)</code></term> 664 <listitem><simpara>Call <function role="unix">encrypt</function> 665 and <function role="unix">setkey</function>, respectively. 666 <replaceable>block</replaceable> and &key-r; are of type 667 <literal role="type">(&vector; (&unsigned-byte-t; 8) 8)</literal>. 668 <replaceable>decrypt-p</replaceable> is &boolean-t;. 669 </simpara></listitem></varlistentry> 670</variablelist></section> 671 672<section id="sys-log"><title>Syslog</title> 673<variablelist> 674 <varlistentry id="openlog"><term><code>(POSIX:OPENLOG ident &key-amp; 675 :PID :CONS :NDELAY :ODELAY :NOWAIT :FACILITY)</code></term> 676 <listitem><simpara>Calls <function role="unix">openlog</function> 677 </simpara></listitem></varlistentry> 678 <varlistentry id="setlogmask"><term><code>(POSIX:SETLOGMASK 679 maskpri)</code></term> 680 <listitem><simpara>Calls <function role="unix">setlogmask</function>. 681 </simpara></listitem></varlistentry> 682 <varlistentry id="syslog"><term><code>(POSIX:SYSLOG severity facility 683 &fmt-r; &rest-amp; &args-r;)</code></term> 684 <listitem><simpara>Calls <function role="unix">syslog</function> on 685 <code>(&apply; &format; &nil; &fmt-r; &args-r;)</code>.</simpara> 686 <simpara>No <literal role="data">%</literal> conversion is performed, 687 you must do all formatting in Lisp.</simpara></listitem></varlistentry> 688 <varlistentry id="closelog"><term><code>(POSIX:CLOSELOG)</code></term> 689 <listitem><simpara>Calls <function role="unix">closelog</function>. 690</simpara></listitem></varlistentry></variablelist></section> 691 692<section id="processes"><title>Processes</title> 693<variablelist> 694 <varlistentry id="process-id"><term><code>(OS:PROCESS-ID)</code></term> 695 <listitem><simpara>Return the process ID 696 (on &unix; calls <function role="unix">getpid</function>, 697 on &win32; calls <function role="win32">GetCurrentProcessId</function>) 698 </simpara></listitem></varlistentry> 699 <varlistentry id="priority"><term><code>(OS:PRIORITY &pid-r; 700 &optional-amp; &what-r;)</code></term> 701 <term><code>(&setf; (OS:PRIORITY &pid-r; &optional-amp; &what-r;) 702 priority)</code></term> 703 <listitem><para>Return or set the process priority, platform-dependent 704 &integer-t; or platform-independent &symbol-t;, one of 705 <simplelist columns="3"> 706 <member><constant>:REALTIME</constant></member> 707 <member><constant>:HIGH</constant></member> 708 <member><constant>:ABOVE-NORMAL</constant></member> 709 <member><constant>:NORMAL</constant></member> 710 <member><constant>:BELOW-NORMAL</constant></member> 711 <member><constant>:LOW</constant></member> 712 <member><constant>:IDLE</constant></member></simplelist> 713 On &unix; calls <function role="unix">getpriority</function> 714 and <function role="unix">setpriority</function>, on 715 &win32; calls <function role="win32">GetPriorityClass</function> and 716 <function role="win32">SetPriorityClass</function>.</para> 717 </listitem></varlistentry> 718 <varlistentry id="kill"><term><code>(POSIX:KILL &pid-r; &sig-r;)</code></term> 719 <listitem><simpara>Calls <function role="unix">kill</function>. 720 </simpara></listitem></varlistentry> 721 <varlistentry id="getppid"><term><code>(POSIX:GETPPID)</code></term> 722 <listitem><simpara>Calls <function role="unix">getppid</function>. 723 </simpara></listitem></varlistentry> 724 <varlistentry id="getpgrp"><term><code>(POSIX:GETPGRP)</code></term> 725 <listitem><simpara>Calls <function role="unix">getpgrp</function>. 726 </simpara></listitem></varlistentry> 727 <varlistentry id="setpgrp"><term><code>(POSIX:SETPGRP)</code></term> 728 <listitem><simpara>Calls <function role="unix">setpgrp</function>; 729 on non-&posix; systems where it requires 2 arguments (legacy 730 BSD-style), it is called as <code>setpgrp(0,0)</code>. 731 </simpara></listitem></varlistentry> 732 <varlistentry id="getsid"><term><code>(POSIX:GETSID &pid-r;)</code></term> 733 <listitem><simpara>Calls <function role="unix">getsid</function>. 734 </simpara></listitem></varlistentry> 735 <varlistentry id="setsid"><term><code>(POSIX:SETSID)</code></term> 736 <listitem><simpara>Calls <function role="unix">setsid</function>. 737 </simpara></listitem></varlistentry> 738 <varlistentry id="getpgid"><term><code>(POSIX:PGID &pid-r;)</code></term> 739 <term><code>(&setf; (POSIX:PGID &pid-r;) 740 <replaceable>pgid</replaceable>)</code></term> 741 <listitem><simpara>Call <function role="unix">getpgid</function> and 742 <function role="unix">setpgid</function>.</simpara></listitem></varlistentry> 743 <varlistentry id="setreuid"><term><code>(POSIX:SETREUID 744 ruid euid)</code></term> 745 <listitem><simpara>Call <function role="unix">setreuid</function>. 746 </simpara></listitem></varlistentry> 747 <varlistentry id="setregid"><term><code>(POSIX:SETREGID 748 rgid egid)</code></term> 749 <listitem><simpara>Call <function role="unix">setregid</function>. 750 </simpara></listitem></varlistentry> 751 <varlistentry id="getuid"><term><code>(POSIX:UID)</code></term> 752 <term><code>(&setf; (POSIX:UID) &uid-r;)</code></term> 753 <listitem><simpara>Call <function role="unix">getuid</function> and 754 <function role="unix">setuid</function>.</simpara></listitem></varlistentry> 755 <varlistentry id="getgid"><term><code>(POSIX:GID)</code></term> 756 <term><code>(&setf; (POSIX:GID) &gid-r;)</code></term> 757 <listitem><simpara>Call <function role="unix">getgid</function> and 758 <function role="unix">setgid</function>.</simpara></listitem></varlistentry> 759 <varlistentry id="geteuid"><term><code>(POSIX:EUID)</code></term> 760 <term><code>(&setf; (POSIX:EUID) &uid-r;)</code></term> 761 <listitem><simpara>Call <function role="unix">geteuid</function> and 762 <function role="unix">seteuid</function>.</simpara></listitem></varlistentry> 763 <varlistentry id="getegid"><term><code>(POSIX:EGID)</code></term> 764 <term><code>(&setf; (POSIX:EGID) &gid-r;)</code></term> 765 <listitem><simpara>Call <function role="unix">getegid</function> and 766 <function role="unix">setegid</function>.</simpara></listitem></varlistentry> 767 <varlistentry id="getgroups"><term><code>(POSIX:GROUPS)</code></term> 768 <term><code>(&setf; (POSIX:GROUPS) &list-r;)</code></term> 769 <listitem><simpara>Call <function role="unix">getgroups</function> and 770 <function role="bsd">setgroups</function>. 771 </simpara></listitem></varlistentry> 772 <varlistentry id="wait"><term><code>(&wait; &key-amp; :PID :USAGE 773 :NOHANG :UNTRACED :STOPPED :EXITED :CONTINUED :NOWAIT)</code></term> 774 <listitem><simpara>Wait for termination of the child process 775 <constant>:PID</constant> (or any child process if not specified).</simpara> 776 <simpara>If <constant>:NOHANG</constant> is specifed, return &zero; 777 as the only value immediately if no child process has terminated.</simpara> 778 <simpara>Otherwise, the first return value is the &pid-r; of the 779 terminated child process.</simpara> 780 <para>The second and third return values depend on the way the 781 process terminated:<variablelist> 782 <varlistentry><term>2nd value = <constant>:EXITED</constant></term> 783 <term>3rd value = <replaceable>exit status</replaceable></term> 784 <listitem><simpara>if the child terminated normally, e.g., by 785 calling <function role="unix">exit</function>. 786 </simpara></listitem></varlistentry> 787 <varlistentry><term>2nd value = <constant>:SIGNALED</constant></term> 788 <term>3rd value = &sig-r;</term> 789 <listitem><simpara>if the child process was terminated by a &sig-r;. 790 </simpara></listitem></varlistentry> 791 <varlistentry><term>2nd value = <constant>:STOPPED</constant></term> 792 <term>3rd value = &sig-r;</term> 793 <listitem><simpara>if the child process was stopped by delivery of 794 a &sig-r;.</simpara></listitem></varlistentry> 795 <varlistentry><term>2nd value = <constant>:CONTINUED</constant></term> 796 <term>3rd value = &nil;</term> 797 <listitem><simpara>if the child process has continued from a job 798 control stop.</simpara></listitem></varlistentry> 799 <varlistentry><term>2nd value = &nil;</term> 800 <term>3rd value = &number-r;</term> 801 <listitem><simpara>if &clisp; could not figure out what has happened. 802 Please read your local <function role="unix">waitpid</function> 803 manual and send us a patch.</simpara></listitem></varlistentry> 804 </variablelist></para> 805 <simpara>The fourth value is only returned if <constant>:USAGE</constant> 806 is non-&nil; and in that case it is a structure describing resource 807 usage by the terminated process, similar to what &usage; returns.</simpara> 808 <simpara>To avoid race conditions, it is important to start your 809 subprocesses &and-e; &wait; for them inside the &body-r; of 810 a &with-subprocesses; form.</simpara> 811 <simpara>Calls <function role="unix">waitpid</function> and 812 (when the <constant>:USAGE</constant> argument is non-&nil;) 813 <function role="bsd">wait4</function>.</simpara></listitem></varlistentry> 814 <varlistentry id="with-subprocesses"><term><code>(&with-subprocesses; 815 &body-amp;)</code></term> 816 <listitem><simpara>Evaluate &body-r; while receiving signals from 817 subprocesses; your &run-prog; and related &wait; calls should be 818 inside it.</simpara></listitem></varlistentry> 819</variablelist></section> 820 821<section id="accounting"><title>Accounting</title> 822<variablelist> 823 <varlistentry id="endutxent"><term><code>(POSIX:ENDUTXENT)</code></term> 824 <listitem><simpara>Calls <function role="unix">endutxent</function>. 825 </simpara></listitem></varlistentry> 826 <varlistentry id="getutxent"><term><code>(POSIX:GETUTXENT 827 &optional-amp; utmpx)</code></term> 828 <listitem><simpara>Calls <function role="unix">getutxent</function>, 829 returns a &structure-object-t; of type <type>POSIX:UTMPX</type>, 830 which can be passed to subsequent calls to this function and re-used. 831 </simpara></listitem></varlistentry> 832 <varlistentry id="getutxid"><term><code>(POSIX:GETUTXID id)</code></term> 833 <listitem><simpara>Calls <function role="unix">getutxid</function>, 834 the argument is filled and returned.</simpara></listitem></varlistentry> 835 <varlistentry id="getutxline"><term><code>(POSIX:GETUTXLINE line)</code></term> 836 <listitem><simpara>Calls <function role="unix">getutxline</function>, 837 the argument is filled and returned.</simpara></listitem></varlistentry> 838 <varlistentry id="pututxline"><term><code>(POSIX:PUTUTXLINE 839 utmpx)</code></term> 840 <listitem><simpara>Calls <function role="unix">pututxline</function>, 841 the argument is filled and returned.</simpara></listitem></varlistentry> 842 <varlistentry id="setutxent"><term><code>(POSIX:SETUTXENT)</code></term> 843 <listitem><simpara>Calls <function role="unix">setutxent</function>. 844</simpara></listitem></varlistentry></variablelist></section> 845 846<section id="posix-time"><title>Time and Data Conversion</title> 847<variablelist><varlistentry id="strtime"><term><code>(OS:STRING-TIME 848 &fmt-r; &optional-amp; &object-r; timezone)</code></term> 849 <listitem><itemizedlist><listitem><simpara>When &object-r; is a &string-t;, 850 it is parsed into a universal time according to &fmt-r; by 851 <function role="unix">strptime</function>.</simpara></listitem> 852 <listitem><simpara>When it is an &integer-t;, it is formatted according 853 to &fmt-r; by <function role="unix">strftime</function>. 854 &object-r; defaults to <code>(&get-universal-time;)</code>. 855</simpara></listitem></itemizedlist></listitem></varlistentry> 856<varlistentry id="getdate"><term><code>(OS:GETDATE &string-r; 857 &optional-amp; timezone)</code></term> 858 <listitem><simpara>Parse the &string-r; into a universal time using 859 <function role="unix">getdate</function>.</simpara> 860 <simpara>If the the &env-var; <envar>DATEMSK</envar> is not set when 861 &clisp; is invoked, &clisp; sets it to point to the file 862 <filename role="clisp">modules/syscalls/datemsk</filename>, installed as 863 <code>(&merge-pathnames; "syscalls/datemsk" &libdir;)</code>. 864</simpara></listitem></varlistentry></variablelist></section> 865 866<section id="strverscmp"><title>String comparision</title> 867<para>Functions <simplelist columns="1"> 868 <member><code>(OS:VERSION< &x1-r; &x2-r;)</code></member> 869 <member><code>(OS:VERSION<= &x1-r; &x2-r;)</code></member> 870 <member><code>(OS:VERSION> &x1-r; &x2-r;)</code></member> 871 <member><code>(OS:VERSION>= &x1-r; &x2-r;)</code></member></simplelist> 872 compare two &string-t;s as version numbers (e.g., 873 <literal role="data">"foo10"</literal> is <emphasis>greater</emphasis> than 874 <literal role="data">"foo9"</literal>) using 875 <function role="gnu">strverscmp</function> and return a &boolean-t;.</para> 876<para>Function <function>OS:VERSION-COMPARE</function> does the same but 877returns either <literal role="data"><</literal>, 878<literal role="data">></literal> or <literal role="data">=</literal>. 879</para></section> 880 881<section id="wildcard"><title>Wildcard Matching</title> 882<para>Wildcards describe sets of file names; see <quote>&path-match; 883Notation</quote> for the syntax description.</para> 884<formalpara id="fnmatch-f"><title><code>(POSIX:FNMATCH &pattern-r; &string-r; 885 &key-amp; :PATHNAME :PERIOD :NOESCAPE (:CASE-SENSITIVE &t;))</code></title> 886<para>This function returns a non-&nil; value if the &string-r; matches 887 the &pattern-r; by calling <function role="unix">fnmatch</function>. 888</para></formalpara> 889 890<formalpara id="fnmatch-matcher"><title><code>(POSIX:FNMATCH-MATCHER 891 &pattern-r;)</code></title> 892 <para>This function is a valid value for &apropos-matcher;. 893</para></formalpara> 894 895<note><para>These two functions used to reside in a separate package 896<quote role="package">WILDCARD</quote>, which has been now deprecated. 897</para></note> 898</section> 899 900<section id="mk-xterm-io"><title>XTerm</title> 901<para><code>(&mk-xterm-io; &key-amp; title xterm)</code> 902 When running under the &X;, you can create a &bidi-s;, which uses a new 903 dedicated text window (created by the executable specified by 904 the <constant>:XTERM</constant> argument which should be compatible 905 with <command>xterm</command> and <command>rxvt</command>, i.e., accept 906 options <option>-n</option>, <option>-T</option>, and <option>-e</option>) 907 using the function &mk-xterm-io;: <programlisting language="lisp"> 908(&setq; &error-output-var; 909 (&setq; &debug-io-var; 910 (&mk-xterm-io; :title "clisp errors and debug"))) 911</programlisting></para><simpara>&unix-only;</simpara> 912</section> 913 914<section id="stdio"><title>Standard file input and output</title> 915<para>We define the type <type>FFI:file</type> = &foreign-pointer-t; and 916 the following functions:<simplelist columns="1"> 917 <member><code>(<function role="unix">fopen</function> &filename-r; 918 &mode-r;)</code></member> 919 <member><code>(<function role="unix">fdopen</function> fd 920 &mode-r;)</code></member> 921 <member><code>(<function role="unix">freopen</function> &filename-r; 922 &mode-r; &file-r;)</code></member> 923 <member><code>(<function role="unix">fclose</function> 924 &file-r;)</code></member> 925 <member><code>(<function role="unix">fflush</function> 926 &file-r;)</code></member> 927 <!-- <member><code>(<function role="unix">fgetc</function> 928 &file-r;)</code></member> 929 <member><code>(<function role="unix">fputc</function> int 930 &file-r;)</code></member> 931 <member><code>(<function role="unix">ungetc</function> int 932 &file-r;)</code></member> --> 933 <member><code>(<function role="unix">clearerr</function> 934 &file-r;)</code></member> 935 <member><code>(<function role="unix">feof</function> 936 &file-r;)</code></member> 937 <member><code>(<function role="unix">ferror</function> 938 &file-r;)</code></member> 939 <member><code>(<function role="unix">fileno</function> 940 &file-r;)</code></member> 941 </simplelist>call their namesakes defined in &stdio;.</para> 942<para>Functions <simplelist> 943 <member><function>OS:FOPEN</function></member> 944 <member><function>OS:FDOPEN</function></member> 945 <member><function>OS:FREOPEN</function></member> 946 <member><function>OS:FCLOSE</function></member> 947 <member><function>OS:FFLUSH</function></member> 948 <member><function>OS:FILENO</function></member> 949 </simplelist> may &signal; an &error-t;.</para> 950 <variablelist><title>Return values</title> 951 <varlistentry><term><function>OS:FOPEN</function></term> 952 <term><function>OS:FDOPEN</function></term> 953 <listitem><simpara><type>FFI:file</type> = &foreign-pointer-t; 954 </simpara></listitem></varlistentry> 955 <varlistentry><term><function>OS:FREOPEN</function></term> 956 <term><function>OS:FCLOSE</function></term> 957 <term><function>OS:FFLUSH</function></term> 958 <term><function>OS:CLEARERR</function></term> 959 <listitem><simpara>no values (they modify their &file-r; argument in place) 960 </simpara></listitem></varlistentry> 961 <varlistentry><term><function>OS:FEOF</function></term> 962 <term><function>OS:FERROR</function></term> 963 <listitem><simpara>&boolean-t;</simpara></listitem></varlistentry> 964 <varlistentry><term><function>OS:FILENO</function></term> 965 <listitem><simpara>&integer-t; (&file-des;)</simpara> 966 </listitem></varlistentry></variablelist> 967 <para>We also define 3 constants <simplelist columns="1"> 968 <member><constant>OS:STDIN</constant></member> 969 <member><constant>OS:STDOUT</constant></member> 970 <member><constant>OS:STDERR</constant></member> 971 </simplelist></para> 972<simplesect id="stdio-rationale"><title>Rationale</title> 973<formalpara id="stdio-ffi"><title>Iterface to foreign libraries</title> 974 <para>This functionality can be used by &ffi-pac; &module;s which 975 interface to functions which use the &c-lang; <type>FILE*</type> pointers. 976 E.g., &postgresql-mod; has a function <function role="pq">PQtrace</function> 977 which expects a <type>FILE*</type> argument. 978 You can use <function>OS:FOPEN</function> 979 and <function>OS:FCLOSE</function> for that.</para></formalpara> 980<formalpara id="stdio-wild"><title>Bypass &cl; filename processing</title> 981 <para>You can also use this functionality to access files whose 982 names are interpreted as wild by &cl;. E.g.,<programlisting language="lisp"> 983(&let; ((file (posix:fopen "foo*" "r"))) 984 (&unwind-protect; 985 (&with-open-stream; (s (&make-stream; (posix:fileno file))) 986 (&read-line; s)) 987 (posix:fclose file))) 988</programlisting></para></formalpara></simplesect> 989</section> 990 991<section id="errno"><title>Error handling</title> 992<para>To handle errors in foreign functions, the following four 993 functions are provided: <variablelist> 994<varlistentry><term><code>(POSIX:ERRNO &optional-amp; &ecode-r;)</code></term> 995 <listitem><simpara>When &ecode-r; is supplied, &errno; is set (useful 996 before a system call which sets &errno; as the only way to report an 997 error).</simpara> 998 <simpara>If &ecode-r; is a &number-t;, the corresponding &keyword-t; 999 is returned and vice versa.</simpara> 1000 <simpara>When &ecode-r; is not supplied, the current &errno; is 1001 returned as a keyword if possible, a number otherwise.</simpara> 1002 <simpara>When &ecode-r; is &t;, all known error codes are 1003 returned as an &alist;.</simpara></listitem></varlistentry> 1004 <varlistentry><term><code>(OS:LAST-ERROR &optional-amp; 1005 &ecode-r;)</code></term> 1006 <listitem><simpara>Just like <function>POSIX:ERRNO</function>, 1007 but uses <function role="win32">GetLastError</function> 1008 and <function role="win32">SetLastError</function> instead 1009 of &errno;.</simpara> 1010 <simpara>&win32-only;</simpara></listitem></varlistentry> 1011<varlistentry><term><code>(POSIX:STRERROR &optional-amp; 1012 &ecode-r;)</code></term> 1013 <listitem><simpara>Return a string description of &ecode-r;. 1014 When &ecode-r; is not supplied, &errno; is used.</simpara> 1015 <simpara>This calls &strerror;.</simpara></listitem></varlistentry> 1016<varlistentry><term><code>(OS:FORMAT-MESSAGE &optional-amp; 1017 &ecode-r;)</code></term> 1018 <listitem><simpara>Just like <function>POSIX:STRERROR</function>, 1019 but uses <function role="win32">FormatMessage</function> 1020 and <function role="win32">GetLastError</function>.</simpara> 1021 <simpara>&win32-only;</simpara></listitem></varlistentry> 1022</variablelist></para> 1023</section> 1024 1025<section id="misc"><title>Miscellanea</title> 1026<variablelist> 1027 <varlistentry id="clipboard"><term><code>(OS:CLIPBOARD)</code></term> 1028 <term><code>(&setf; (OS:CLIPBOARD) &object-r;)</code></term> 1029 <listitem><simpara>Get 1030 (using <function role="win32">GetClipboardData</function>) a set 1031 (using <function role="win32">SetClipboardData</function>) 1032 the windows clipboard.</simpara> 1033 <simpara>Return a &string-t;; convert &object-r; to a &string-t; 1034 using &princ-to-string;.</simpara> 1035 <simpara>&win32-cygwin-only;</simpara></listitem></varlistentry> 1036</variablelist></section> 1037 1038</section> 1039