1Unix(3) OCaml library Unix(3)
2
6 Unix - Interface to the Unix system.
7
9 Module Unix
10
12 Module Unix
13 : sig end
14 Interface to the Unix system.
17 To use the labeled version of this module, add module Unix = UnixLabels
19 in your implementation.
20 Note: all the functions of this module (except Unix.error_message and
22 Unix.handle_unix_error ) are liable to raise the Unix.Unix_error excep‐
23 tion whenever the underlying system call signals an error.
24 Error report
32 type error =
33 | E2BIG (* Argument list too long
34 *)
35 | EACCES (* Permission denied
36 *)
37 | EAGAIN (* Resource temporarily unavailable; try again
38 *)
39 | EBADF (* Bad file descriptor
40 *)
41 | EBUSY (* Resource unavailable
42 *)
43 | ECHILD (* No child process
44 *)
45 | EDEADLK (* Resource deadlock would occur
46 *)
47 | EDOM (* Domain error for math functions, etc.
48 *)
49 | EEXIST (* File exists
50 *)
51 | EFAULT (* Bad address
52 *)
53 | EFBIG (* File too large
54 *)
55 | EINTR (* Function interrupted by signal
56 *)
57 | EINVAL (* Invalid argument
58 *)
59 | EIO (* Hardware I/O error
60 *)
61 | EISDIR (* Is a directory
62 *)
63 | EMFILE (* Too many open files by the process
64 *)
65 | EMLINK (* Too many links
66 *)
67 | ENAMETOOLONG (* Filename too long
68 *)
69 | ENFILE (* Too many open files in the system
70 *)
71 | ENODEV (* No such device
72 *)
73 | ENOENT (* No such file or directory
74 *)
75 | ENOEXEC (* Not an executable file
76 *)
77 | ENOLCK (* No locks available
78 *)
79 | ENOMEM (* Not enough memory
80 *)
81 | ENOSPC (* No space left on device
82 *)
83 | ENOSYS (* Function not supported
84 *)
85 | ENOTDIR (* Not a directory
86 *)
87 | ENOTEMPTY (* Directory not empty
88 *)
89 | ENOTTY (* Inappropriate I/O control operation
90 *)
91 | ENXIO (* No such device or address
92 *)
93 | EPERM (* Operation not permitted
94 *)
95 | EPIPE (* Broken pipe
96 *)
97 | ERANGE (* Result too large
98 *)
99 | EROFS (* Read-only file system
100 *)
101 | ESPIPE (* Invalid seek e.g. on a pipe
102 *)
103 | ESRCH (* No such process
104 *)
105 | EXDEV (* Invalid link
106 *)
107 | EWOULDBLOCK (* Operation would block
108 *)
109 | EINPROGRESS (* Operation now in progress
110 *)
111 | EALREADY (* Operation already in progress
112 *)
113 | ENOTSOCK (* Socket operation on non-socket
114 *)
115 | EDESTADDRREQ (* Destination address required
116 *)
117 | EMSGSIZE (* Message too long
118 *)
119 | EPROTOTYPE (* Protocol wrong type for socket
120 *)
121 | ENOPROTOOPT (* Protocol not available
122 *)
123 | EPROTONOSUPPORT (* Protocol not supported
124 *)
125 | ESOCKTNOSUPPORT (* Socket type not supported
126 *)
127 | EOPNOTSUPP (* Operation not supported on socket
128 *)
129 | EPFNOSUPPORT (* Protocol family not supported
130 *)
131 | EAFNOSUPPORT (* Address family not supported by protocol family
132 *)
133 | EADDRINUSE (* Address already in use
134 *)
135 | EADDRNOTAVAIL (* Can't assign requested address
136 *)
137 | ENETDOWN (* Network is down
138 *)
139 | ENETUNREACH (* Network is unreachable
140 *)
141 | ENETRESET (* Network dropped connection on reset
142 *)
143 | ECONNABORTED (* Software caused connection abort
144 *)
145 | ECONNRESET (* Connection reset by peer
146 *)
147 | ENOBUFS (* No buffer space available
148 *)
149 | EISCONN (* Socket is already connected
150 *)
151 | ENOTCONN (* Socket is not connected
152 *)
153 | ESHUTDOWN (* Can't send after socket shutdown
154 *)
155 | ETOOMANYREFS (* Too many references: can't splice
156 *)
157 | ETIMEDOUT (* Connection timed out
158 *)
159 | ECONNREFUSED (* Connection refused
160 *)
161 | EHOSTDOWN (* Host is down
162 *)
163 | EHOSTUNREACH (* No route to host
164 *)
165 | ELOOP (* Too many levels of symbolic links
166 *)
167 | EOVERFLOW (* File size or position not representable
168 *)
169 | EUNKNOWNERR of int
170 (* Unknown error
171 *)
172 The type of error codes. Errors defined in the POSIX standard and ad‐
175 ditional errors from UNIX98 and BSD. All other errors are mapped to
176 EUNKNOWNERR.
177 exception Unix_error of error * string * string
181 Raised by the system calls below when an error is encountered. The
184 first component is the error code; the second component is the function
185 name; the third component is the string parameter to the function, if
186 it has one, or the empty string otherwise.
187 UnixLabels.Unix_error and Unix.Unix_error are the same, and catching
190 one will catch the other.
191 val error_message : error -> string
195 Return a string describing the given error code.
197 val handle_unix_error : ('a -> 'b) -> 'a -> 'b
201 handle_unix_error f x applies f to x and returns the result. If the
204 exception Unix.Unix_error is raised, it prints a message describing the
205 error and exits with code 2.
206 Access to the process environment
211 val environment : unit -> string array
212 Return the process environment, as an array of strings with the format
214 ``variable=value''. The returned array is empty if the process has
215 special privileges.
216 val unsafe_environment : unit -> string array
220 Return the process environment, as an array of strings with the format
222 ``variable=value''. Unlike Unix.environment , this function returns a
223 populated array even if the process has special privileges. See the
224 documentation for Unix.unsafe_getenv for more details.
225 Since 4.06.0 (4.12.0 in UnixLabels)
228 val getenv : string -> string
232 Return the value associated to a variable in the process environment,
234 unless the process has special privileges.
235 Raises Not_found if the variable is unbound or the process has special
238 privileges.
239 This function is identical to Sys.getenv .
241 val unsafe_getenv : string -> string
245 Return the value associated to a variable in the process environment.
247 Unlike Unix.getenv , this function returns the value even if the
249 process has special privileges. It is considered unsafe because the
250 programmer of a setuid or setgid program must be careful to avoid using
251 maliciously crafted environment variables in the search path for exe‐
252 cutables, the locations for temporary files or logs, and the like.
253 Since 4.06.0
256 Raises Not_found if the variable is unbound.
259 val putenv : string -> string -> unit
263 putenv name value sets the value associated to a variable in the
266 process environment. name is the name of the environment variable, and
267 value its new associated value.
268 Process handling
273 type process_status =
274 | WEXITED of int
275 (* The process terminated normally by exit ; the argument is the re‐
276 turn code.
277 *)
278 | WSIGNALED of int
279 (* The process was killed by a signal; the argument is the signal
280 number.
281 *)
282 | WSTOPPED of int
283 (* The process was stopped by a signal; the argument is the signal
284 number.
285 *)
286 The termination status of a process. See module Sys for the defini‐
289 tions of the standard signal numbers. Note that they are not the num‐
290 bers used by the OS.
291 type wait_flag =
294 | WNOHANG (* Do not block if no child has died yet, but immediately
295 return with a pid equal to 0.
296 *)
297 | WUNTRACED (* Report also the children that receive stop signals.
298 *)
299 Flags for Unix.waitpid .
302 val execv : string -> string array -> 'a
306 execv prog args execute the program in file prog , with the arguments
309 args , and the current process environment. These execv* functions
310 never return: on success, the current program is replaced by the new
311 one.
312 Raises Unix_error on failure
315 val execve : string -> string array -> string array -> 'a
319 Same as Unix.execv , except that the third argument provides the envi‐
321 ronment to the program executed.
322 val execvp : string -> string array -> 'a
326 Same as Unix.execv , except that the program is searched in the path.
328 val execvpe : string -> string array -> string array -> 'a
332 Same as Unix.execve , except that the program is searched in the path.
334 val fork : unit -> int
338 Fork a new process. The returned integer is 0 for the child process,
340 the pid of the child process for the parent process.
341 On Windows: not implemented, use Unix.create_process or threads.
343 val wait : unit -> int * process_status
347 Wait until one of the children processes die, and return its pid and
349 termination status.
350 On Windows: not implemented, use Unix.waitpid .
352 val waitpid : wait_flag list -> int -> int * process_status
356 Same as Unix.wait , but waits for the child process whose pid is given.
358 A pid of -1 means wait for any child. A pid of 0 means wait for any
359 child in the same process group as the current process. Negative pid
360 arguments represent process groups. The list of options indicates
361 whether waitpid should return immediately without waiting, and whether
362 it should report stopped children.
363 On Windows: can only wait for a given PID, not any child process.
365 val system : string -> process_status
369 Execute the given command, wait until it terminates, and return its
371 termination status. The string is interpreted by the shell /bin/sh (or
372 the command interpreter cmd.exe on Windows) and therefore can contain
373 redirections, quotes, variables, etc. To properly quote whitespace and
374 shell special characters occurring in file names or command arguments,
375 the use of Filename.quote_command is recommended. The result WEXITED
376 127 indicates that the shell couldn't be executed.
377 val _exit : int -> 'a
381 Terminate the calling process immediately, returning the given status
383 code to the operating system: usually 0 to indicate no errors, and a
384 small positive integer to indicate failure. Unlike exit , Unix._exit
385 performs no finalization whatsoever: functions registered with at_exit
386 are not called, input/output channels are not flushed, and the C
387 run-time system is not finalized either.
388 The typical use of Unix._exit is after a Unix.fork operation, when the
390 child process runs into a fatal error and must exit. In this case, it
391 is preferable to not perform any finalization action in the child
392 process, as these actions could interfere with similar actions per‐
393 formed by the parent process. For example, output channels should not
394 be flushed by the child process, as the parent process may flush them
395 again later, resulting in duplicate output.
396 Since 4.12.0
399 val getpid : unit -> int
403 Return the pid of the process.
405 val getppid : unit -> int
409 Return the pid of the parent process.
411 On Windows: not implemented (because it is meaningless).
413 val nice : int -> int
417 Change the process priority. The integer argument is added to the
419 ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
420 ties.) Return the new nice value.
421 On Windows: not implemented.
423 Basic file input/output
428 type file_descr
429 The abstract type of file descriptors.
432 val stdin : file_descr
436 File descriptor for standard input.
438 val stdout : file_descr
442 File descriptor for standard output.
444 val stderr : file_descr
448 File descriptor for standard error.
450 type open_flag =
453 | O_RDONLY (* Open for reading
454 *)
455 | O_WRONLY (* Open for writing
456 *)
457 | O_RDWR (* Open for reading and writing
458 *)
459 | O_NONBLOCK (* Open in non-blocking mode
460 *)
461 | O_APPEND (* Open for append
462 *)
463 | O_CREAT (* Create if nonexistent
464 *)
465 | O_TRUNC (* Truncate to 0 length if existing
466 *)
467 | O_EXCL (* Fail if existing
468 *)
469 | O_NOCTTY (* Don't make this dev a controlling tty
470 *)
471 | O_DSYNC (* Writes complete as `Synchronised I/O data integrity com‐
472 pletion'
473 *)
474 | O_SYNC (* Writes complete as `Synchronised I/O file integrity com‐
475 pletion'
476 *)
477 | O_RSYNC (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
478 *)
479 | O_SHARE_DELETE (* Windows only: allow the file to be deleted while
480 still open
481 *)
482 | O_CLOEXEC (* Set the close-on-exec flag on the descriptor returned
483 by Unix.openfile . See Unix.set_close_on_exec for more information.
484 *)
485 | O_KEEPEXEC (* Clear the close-on-exec flag. This is currently the
486 default.
487 *)
488 The flags to Unix.openfile .
491 type file_perm = int
494 The type of file access rights, e.g. 0o640 is read and write for user,
497 read for group, none for others
498 val openfile : string -> open_flag list -> file_perm -> file_descr
502 Open the named file with the given flags. Third argument is the permis‐
504 sions to give to the file if it is created (see Unix.umask ). Return a
505 file descriptor on the named file.
506 val close : file_descr -> unit
510 Close a file descriptor.
512 val fsync : file_descr -> unit
516 Flush file buffers to disk.
518 Since 4.08.0 (4.12.0 in UnixLabels)
521 val read : file_descr -> bytes -> int -> int -> int
525 read fd buf pos len reads len bytes from descriptor fd , storing them
528 in byte sequence buf , starting at position pos in buf . Return the
529 number of bytes actually read.
530 val write : file_descr -> bytes -> int -> int -> int
534 write fd buf pos len writes len bytes to descriptor fd , taking them
537 from byte sequence buf , starting at position pos in buff . Return the
538 number of bytes actually written. write repeats the writing operation
539 until all bytes have been written or an error occurs.
540 val single_write : file_descr -> bytes -> int -> int -> int
544 Same as Unix.write , but attempts to write only once. Thus, if an er‐
546 ror occurs, single_write guarantees that no data has been written.
547 val write_substring : file_descr -> string -> int -> int -> int
551 Same as Unix.write , but take the data from a string instead of a byte
553 sequence.
554 Since 4.02.0
557 val single_write_substring : file_descr -> string -> int -> int -> int
561 Same as Unix.single_write , but take the data from a string instead of
563 a byte sequence.
564 Since 4.02.0
567 Interfacing with the standard input/output library
572 val in_channel_of_descr : file_descr -> in_channel
573 Create an input channel reading from the given descriptor. The channel
575 is initially in binary mode; use set_binary_mode_in ic false if text
576 mode is desired. Text mode is supported only if the descriptor refers
577 to a file or pipe, but is not supported if it refers to a socket.
578 On Windows: set_binary_mode_in always fails on channels created with
580 this function.
581 Beware that input channels are buffered, so more characters may have
583 been read from the descriptor than those accessed using channel func‐
584 tions. Channels also keep a copy of the current position in the file.
585 Closing the channel ic returned by in_channel_of_descr fd using
587 close_in ic also closes the underlying descriptor fd . It is incorrect
588 to close both the channel ic and the descriptor fd .
589 If several channels are created on the same descriptor, one of the
591 channels must be closed, but not the others. Consider for example a
592 descriptor s connected to a socket and two channels ic = in_chan‐
593 nel_of_descr s and oc = out_channel_of_descr s . The recommended clos‐
594 ing protocol is to perform close_out oc , which flushes buffered output
595 to the socket then closes the socket. The ic channel must not be
596 closed and will be collected by the GC eventually.
597 val out_channel_of_descr : file_descr -> out_channel
601 Create an output channel writing on the given descriptor. The channel
603 is initially in binary mode; use set_binary_mode_out oc false if text
604 mode is desired. Text mode is supported only if the descriptor refers
605 to a file or pipe, but is not supported if it refers to a socket.
606 On Windows: set_binary_mode_out always fails on channels created with
608 this function.
609 Beware that output channels are buffered, so you may have to call flush
611 to ensure that all data has been sent to the descriptor. Channels also
612 keep a copy of the current position in the file.
613 Closing the channel oc returned by out_channel_of_descr fd using
615 close_out oc also closes the underlying descriptor fd . It is incor‐
616 rect to close both the channel ic and the descriptor fd .
617 See Unix.in_channel_of_descr for a discussion of the closing protocol
619 when several channels are created on the same descriptor.
620 val descr_of_in_channel : in_channel -> file_descr
624 Return the descriptor corresponding to an input channel.
626 val descr_of_out_channel : out_channel -> file_descr
630 Return the descriptor corresponding to an output channel.
632 Seeking and truncating
637 type seek_command =
638 | SEEK_SET (* indicates positions relative to the beginning of the
639 file
640 *)
641 | SEEK_CUR (* indicates positions relative to the current position
642 *)
643 | SEEK_END (* indicates positions relative to the end of the file
644 *)
645 Positioning modes for Unix.lseek .
648 val lseek : file_descr -> int -> seek_command -> int
652 Set the current position for a file descriptor, and return the result‐
654 ing offset (from the beginning of the file).
655 val truncate : string -> int -> unit
659 Truncates the named file to the given size.
661 val ftruncate : file_descr -> int -> unit
665 Truncates the file corresponding to the given descriptor to the given
667 size.
668 File status
673 type file_kind =
674 | S_REG (* Regular file
675 *)
676 | S_DIR (* Directory
677 *)
678 | S_CHR (* Character device
679 *)
680 | S_BLK (* Block device
681 *)
682 | S_LNK (* Symbolic link
683 *)
684 | S_FIFO (* Named pipe
685 *)
686 | S_SOCK (* Socket
687 *)
688 type stats = {
693 st_dev : int ; (* Device number
694 *)
695 st_ino : int ; (* Inode number
696 *)
697 st_kind : file_kind ; (* Kind of the file
698 *)
699 st_perm : file_perm ; (* Access rights
700 *)
701 st_nlink : int ; (* Number of links
702 *)
703 st_uid : int ; (* User id of the owner
704 *)
705 st_gid : int ; (* Group ID of the file's group
706 *)
707 st_rdev : int ; (* Device ID (if special file)
708 *)
709 st_size : int ; (* Size in bytes
710 *)
711 st_atime : float ; (* Last access time
712 *)
713 st_mtime : float ; (* Last modification time
714 *)
715 st_ctime : float ; (* Last status change time
716 *)
717 }
718 The information returned by the Unix.stat calls.
721 val stat : string -> stats
725 Return the information for the named file.
727 val lstat : string -> stats
731 Same as Unix.stat , but in case the file is a symbolic link, return the
733 information for the link itself.
734 val fstat : file_descr -> stats
738 Return the information for the file associated with the given descrip‐
740 tor.
741 val isatty : file_descr -> bool
745 Return true if the given file descriptor refers to a terminal or con‐
747 sole window, false otherwise.
748 File operations on large files
753 module LargeFile : sig end
754 File operations on large files. This sub-module provides 64-bit vari‐
757 ants of the functions Unix.LargeFile.lseek (for positioning a file de‐
758 scriptor), Unix.LargeFile.truncate and Unix.LargeFile.ftruncate (for
759 changing the size of a file), and Unix.LargeFile.stat , Unix.Large‐
760 File.lstat and Unix.LargeFile.fstat (for obtaining information on
761 files). These alternate functions represent positions and sizes by
762 64-bit integers (type int64 ) instead of regular integers (type int ),
763 thus allowing operating on files whose sizes are greater than max_int .
764 Mapping files into memory
769 val map_file : file_descr -> ?pos:int64 -> ('a, 'b) Bigarray.kind -> 'c
770 Bigarray.layout -> bool -> int array -> ('a, 'b, 'c) Bigarray.Genar‐
771 ray.t
772 Memory mapping of a file as a Bigarray. map_file fd kind layout shared
774 dims returns a Bigarray of kind kind , layout layout , and dimensions
775 as specified in dims . The data contained in this Bigarray are the
776 contents of the file referred to by the file descriptor fd (as opened
777 previously with Unix.openfile , for example). The optional pos parame‐
778 ter is the byte offset in the file of the data being mapped; it de‐
779 faults to 0 (map from the beginning of the file).
780 If shared is true , all modifications performed on the array are re‐
782 flected in the file. This requires that fd be opened with write per‐
783 missions. If shared is false , modifications performed on the array
784 are done in memory only, using copy-on-write of the modified pages; the
785 underlying file is not affected.
786 Genarray.map_file is much more efficient than reading the whole file in
789 a Bigarray, modifying that Bigarray, and writing it afterwards.
790 To adjust automatically the dimensions of the Bigarray to the actual
792 size of the file, the major dimension (that is, the first dimension for
793 an array with C layout, and the last dimension for an array with For‐
794 tran layout) can be given as -1 . Genarray.map_file then determines
795 the major dimension from the size of the file. The file must contain
796 an integral number of sub-arrays as determined by the non-major dimen‐
797 sions, otherwise Failure is raised.
798 If all dimensions of the Bigarray are given, the file size is matched
800 against the size of the Bigarray. If the file is larger than the Bi‐
801 garray, only the initial portion of the file is mapped to the Bigarray.
802 If the file is smaller than the big array, the file is automatically
803 grown to the size of the Bigarray. This requires write permissions on
804 fd .
805 Array accesses are bounds-checked, but the bounds are determined by the
807 initial call to map_file . Therefore, you should make sure no other
808 process modifies the mapped file while you're accessing it, or a SIGBUS
809 signal may be raised. This happens, for instance, if the file is
810 shrunk.
811 Invalid_argument or Failure may be raised in cases where argument vali‐
814 dation fails.
815 Since 4.06.0
818 Operations on file names
823 val unlink : string -> unit
824 Removes the named file.
826 If the named file is a directory, raises:
828 - EPERM on POSIX compliant system
830 - EISDIR on Linux >= 2.1.132
832 - EACCESS on Windows
834 val rename : string -> string -> unit
839 rename src dst changes the name of a file from src to dst , moving it
842 between directories if needed. If dst already exists, its contents
843 will be replaced with those of src . Depending on the operating sys‐
844 tem, the metadata (permissions, owner, etc) of dst can either be pre‐
845 served or be replaced by those of src .
846 val link : ?follow:bool -> string -> string -> unit
850 link ?follow src dst creates a hard link named dst to the file named
853 src .
854 Raises ENOSYS On Unix if ~follow:_ is requested, but linkat is unavail‐
857 able.
858 Raises ENOSYS On Windows if ~follow:false is requested.
861 val realpath : string -> string
865 realpath p is an absolute pathname for p obtained by resolving all ex‐
868 tra / characters, relative path segments and symbolic links.
869 Since 4.13.0
872 File permissions and ownership
877 type access_permission =
878 | R_OK (* Read permission
879 *)
880 | W_OK (* Write permission
881 *)
882 | X_OK (* Execution permission
883 *)
884 | F_OK (* File exists
885 *)
886 Flags for the Unix.access call.
889 val chmod : string -> file_perm -> unit
893 Change the permissions of the named file.
895 val fchmod : file_descr -> file_perm -> unit
899 Change the permissions of an opened file.
901 On Windows: not implemented.
903 val chown : string -> int -> int -> unit
907 Change the owner uid and owner gid of the named file.
909 On Windows: not implemented.
911 val fchown : file_descr -> int -> int -> unit
915 Change the owner uid and owner gid of an opened file.
917 On Windows: not implemented.
919 val umask : int -> int
923 Set the process's file mode creation mask, and return the previous
925 mask.
926 On Windows: not implemented.
928 val access : string -> access_permission list -> unit
932 Check that the process has the given permissions over the named file.
934 On Windows: execute permission X_OK cannot be tested, just tests for
936 read permission instead.
937 Raises Unix_error otherwise.
940 Operations on file descriptors
945 val dup : ?cloexec:bool -> file_descr -> file_descr
946 Return a new file descriptor referencing the same file as the given de‐
948 scriptor. See Unix.set_close_on_exec for documentation on the cloexec
949 optional argument.
950 val dup2 : ?cloexec:bool -> file_descr -> file_descr -> unit
954 dup2 src dst duplicates src to dst , closing dst if already opened.
957 See Unix.set_close_on_exec for documentation on the cloexec optional
958 argument.
959 val set_nonblock : file_descr -> unit
963 Set the ``non-blocking'' flag on the given descriptor. When the
965 non-blocking flag is set, reading on a descriptor on which there is
966 temporarily no data available raises the EAGAIN or EWOULDBLOCK error
967 instead of blocking; writing on a descriptor on which there is tempo‐
968 rarily no room for writing also raises EAGAIN or EWOULDBLOCK .
969 val clear_nonblock : file_descr -> unit
973 Clear the ``non-blocking'' flag on the given descriptor. See
975 Unix.set_nonblock .
976 val set_close_on_exec : file_descr -> unit
980 Set the ``close-on-exec'' flag on the given descriptor. A descriptor
982 with the close-on-exec flag is automatically closed when the current
983 process starts another program with one of the exec , create_process
984 and open_process functions.
985 It is often a security hole to leak file descriptors opened on, say, a
987 private file to an external program: the program, then, gets access to
988 the private file and can do bad things with it. Hence, it is highly
989 recommended to set all file descriptors ``close-on-exec'', except in
990 the very few cases where a file descriptor actually needs to be trans‐
991 mitted to another program.
992 The best way to set a file descriptor ``close-on-exec'' is to create it
994 in this state. To this end, the openfile function has O_CLOEXEC and
995 O_KEEPEXEC flags to enforce ``close-on-exec'' mode or ``keep-on-exec''
996 mode, respectively. All other operations in the Unix module that cre‐
997 ate file descriptors have an optional argument ?cloexec:bool to indi‐
998 cate whether the file descriptor should be created in ``close-on-exec''
999 mode (by writing ~cloexec:true ) or in ``keep-on-exec'' mode (by writ‐
1000 ing ~cloexec:false ). For historical reasons, the default file de‐
1001 scriptor creation mode is ``keep-on-exec'', if no cloexec optional ar‐
1002 gument is given. This is not a safe default, hence it is highly recom‐
1003 mended to pass explicit cloexec arguments to operations that create
1004 file descriptors.
1005 The cloexec optional arguments and the O_KEEPEXEC flag were introduced
1007 in OCaml 4.05. Earlier, the common practice was to create file de‐
1008 scriptors in the default, ``keep-on-exec'' mode, then call
1009 set_close_on_exec on those freshly-created file descriptors. This is
1010 not as safe as creating the file descriptor in ``close-on-exec'' mode
1011 because, in multithreaded programs, a window of vulnerability exists
1012 between the time when the file descriptor is created and the time
1013 set_close_on_exec completes. If another thread spawns another program
1014 during this window, the descriptor will leak, as it is still in the
1015 ``keep-on-exec'' mode.
1016 Regarding the atomicity guarantees given by ~cloexec:true or by the use
1018 of the O_CLOEXEC flag: on all platforms it is guaranteed that a concur‐
1019 rently-executing Caml thread cannot leak the descriptor by starting a
1020 new process. On Linux, this guarantee extends to concurrently-execut‐
1021 ing C threads. As of Feb 2017, other operating systems lack the neces‐
1022 sary system calls and still expose a window of vulnerability during
1023 which a C thread can see the newly-created file descriptor in
1024 ``keep-on-exec'' mode.
1025 val clear_close_on_exec : file_descr -> unit
1029 Clear the ``close-on-exec'' flag on the given descriptor. See
1031 Unix.set_close_on_exec .
1032 Directories
1037 val mkdir : string -> file_perm -> unit
1038 Create a directory with the given permissions (see Unix.umask ).
1040 val rmdir : string -> unit
1044 Remove an empty directory.
1046 val chdir : string -> unit
1050 Change the process working directory.
1052 val getcwd : unit -> string
1056 Return the name of the current working directory.
1058 val chroot : string -> unit
1062 Change the process root directory.
1064 On Windows: not implemented.
1066 type dir_handle
1069 The type of descriptors over opened directories.
1072 val opendir : string -> dir_handle
1076 Open a descriptor on a directory
1078 val readdir : dir_handle -> string
1082 Return the next entry in a directory.
1084 Raises End_of_file when the end of the directory has been reached.
1087 val rewinddir : dir_handle -> unit
1091 Reposition the descriptor to the beginning of the directory
1093 val closedir : dir_handle -> unit
1097 Close a directory descriptor.
1099 Pipes and redirections
1104 val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
1105 Create a pipe. The first component of the result is opened for reading,
1107 that's the exit to the pipe. The second component is opened for writ‐
1108 ing, that's the entrance to the pipe. See Unix.set_close_on_exec for
1109 documentation on the cloexec optional argument.
1110 val mkfifo : string -> file_perm -> unit
1114 Create a named pipe with the given permissions (see Unix.umask ).
1116 On Windows: not implemented.
1118 High-level process and redirection management
1123 val create_process : string -> string array -> file_descr -> file_descr
1124 -> file_descr -> int
1125 create_process prog args stdin stdout stderr forks a new process that
1128 executes the program in file prog , with arguments args . The pid of
1129 the new process is returned immediately; the new process executes con‐
1130 currently with the current process. The standard input and outputs of
1131 the new process are connected to the descriptors stdin , stdout and
1132 stderr . Passing e.g. Stdlib.stdout for stdout prevents the redirect‐
1133 ion and causes the new process to have the same standard output as the
1134 current process. The executable file prog is searched in the path.
1135 The new process has the same environment as the current process.
1136 val create_process_env : string -> string array -> string array ->
1140 file_descr -> file_descr -> file_descr -> int
1141 create_process_env prog args env stdin stdout stderr works as Unix.cre‐
1144 ate_process , except that the extra argument env specifies the environ‐
1145 ment passed to the program.
1146 val open_process_in : string -> in_channel
1150 High-level pipe and process management. This function runs the given
1152 command in parallel with the program. The standard output of the com‐
1153 mand is redirected to a pipe, which can be read via the returned input
1154 channel. The command is interpreted by the shell /bin/sh (or cmd.exe
1155 on Windows), cf. Unix.system . The Filename.quote_command function
1156 can be used to quote the command and its arguments as appropriate for
1157 the shell being used. If the command does not need to be run through
1158 the shell, Unix.open_process_args_in can be used as a more robust and
1159 more efficient alternative to Unix.open_process_in .
1160 val open_process_out : string -> out_channel
1164 Same as Unix.open_process_in , but redirect the standard input of the
1166 command to a pipe. Data written to the returned output channel is sent
1167 to the standard input of the command. Warning: writes on output chan‐
1168 nels are buffered, hence be careful to call flush at the right times to
1169 ensure correct synchronization. If the command does not need to be run
1170 through the shell, Unix.open_process_args_out can be used instead of
1171 Unix.open_process_out .
1172 val open_process : string -> in_channel * out_channel
1176 Same as Unix.open_process_out , but redirects both the standard input
1178 and standard output of the command to pipes connected to the two re‐
1179 turned channels. The input channel is connected to the output of the
1180 command, and the output channel to the input of the command. If the
1181 command does not need to be run through the shell,
1182 Unix.open_process_args can be used instead of Unix.open_process .
1183 val open_process_full : string -> string array -> in_channel *
1187 out_channel * in_channel
1188 Similar to Unix.open_process , but the second argument specifies the
1190 environment passed to the command. The result is a triple of channels
1191 connected respectively to the standard output, standard input, and
1192 standard error of the command. If the command does not need to be run
1193 through the shell, Unix.open_process_args_full can be used instead of
1194 Unix.open_process_full .
1195 val open_process_args_in : string -> string array -> in_channel
1199 open_process_args_in prog args runs the program prog with arguments
1202 args . The new process executes concurrently with the current process.
1203 The standard output of the new process is redirected to a pipe, which
1204 can be read via the returned input channel.
1205 The executable file prog is searched in the path. This behaviour
1207 changed in 4.12; previously prog was looked up only in the current di‐
1208 rectory.
1209 The new process has the same environment as the current process.
1211 Since 4.08.0
1214 val open_process_args_out : string -> string array -> out_channel
1218 Same as Unix.open_process_args_in , but redirect the standard input of
1220 the new process to a pipe. Data written to the returned output channel
1221 is sent to the standard input of the program. Warning: writes on out‐
1222 put channels are buffered, hence be careful to call flush at the right
1223 times to ensure correct synchronization.
1224 Since 4.08.0
1227 val open_process_args : string -> string array -> in_channel *
1231 out_channel
1232 Same as Unix.open_process_args_out , but redirects both the standard
1234 input and standard output of the new process to pipes connected to the
1235 two returned channels. The input channel is connected to the output of
1236 the program, and the output channel to the input of the program.
1237 Since 4.08.0
1240 val open_process_args_full : string -> string array -> string array ->
1244 in_channel * out_channel * in_channel
1245 Similar to Unix.open_process_args , but the third argument specifies
1247 the environment passed to the new process. The result is a triple of
1248 channels connected respectively to the standard output, standard input,
1249 and standard error of the program.
1250 Since 4.08.0
1253 val process_in_pid : in_channel -> int
1257 Return the pid of a process opened via Unix.open_process_in or
1259 Unix.open_process_args_in .
1260 Since 4.08.0 (4.12.0 in UnixLabels)
1263 val process_out_pid : out_channel -> int
1267 Return the pid of a process opened via Unix.open_process_out or
1269 Unix.open_process_args_out .
1270 Since 4.08.0 (4.12.0 in UnixLabels)
1273 val process_pid : in_channel * out_channel -> int
1277 Return the pid of a process opened via Unix.open_process or
1279 Unix.open_process_args .
1280 Since 4.08.0 (4.12.0 in UnixLabels)
1283 val process_full_pid : in_channel * out_channel * in_channel -> int
1287 Return the pid of a process opened via Unix.open_process_full or
1289 Unix.open_process_args_full .
1290 Since 4.08.0 (4.12.0 in UnixLabels)
1293 val close_process_in : in_channel -> process_status
1297 Close channels opened by Unix.open_process_in , wait for the associated
1299 command to terminate, and return its termination status.
1300 val close_process_out : out_channel -> process_status
1304 Close channels opened by Unix.open_process_out , wait for the associ‐
1306 ated command to terminate, and return its termination status.
1307 val close_process : in_channel * out_channel -> process_status
1311 Close channels opened by Unix.open_process , wait for the associated
1313 command to terminate, and return its termination status.
1314 val close_process_full : in_channel * out_channel * in_channel ->
1318 process_status
1319 Close channels opened by Unix.open_process_full , wait for the associ‐
1321 ated command to terminate, and return its termination status.
1322 Symbolic links
1327 val symlink : ?to_dir:bool -> string -> string -> unit
1328 symlink ?to_dir src dst creates the file dst as a symbolic link to the
1331 file src . On Windows, to_dir indicates if the symbolic link points to
1332 a directory or a file; if omitted, symlink examines src using stat and
1333 picks appropriately, if src does not exist then false is assumed (for
1334 this reason, it is recommended that the to_dir parameter be specified
1335 in new code). On Unix, to_dir is ignored.
1336 Windows symbolic links are available in Windows Vista onwards. There
1338 are some important differences between Windows symlinks and their POSIX
1339 counterparts.
1340 Windows symbolic links come in two flavours: directory and regular,
1342 which designate whether the symbolic link points to a directory or a
1343 file. The type must be correct - a directory symlink which actually
1344 points to a file cannot be selected with chdir and a file symlink which
1345 actually points to a directory cannot be read or written (note that
1346 Cygwin's emulation layer ignores this distinction).
1347 When symbolic links are created to existing targets, this distinction
1349 doesn't matter and symlink will automatically create the correct kind
1350 of symbolic link. The distinction matters when a symbolic link is cre‐
1351 ated to a non-existent target.
1352 The other caveat is that by default symbolic links are a privileged op‐
1354 eration. Administrators will always need to be running elevated (or
1355 with UAC disabled) and by default normal user accounts need to be
1356 granted the SeCreateSymbolicLinkPrivilege via Local Security Policy
1357 (secpol.msc) or via Active Directory.
1358 Unix.has_symlink can be used to check that a process is able to create
1361 symbolic links.
1362 val has_symlink : unit -> bool
1366 Returns true if the user is able to create symbolic links. On Windows,
1368 this indicates that the user not only has the SeCreateSymbolicLinkPriv‐
1369 ilege but is also running elevated, if necessary. On other platforms,
1370 this is simply indicates that the symlink system call is available.
1371 Since 4.03.0
1374 val readlink : string -> string
1378 Read the contents of a symbolic link.
1380 Polling
1385 val select : file_descr list -> file_descr list -> file_descr list ->
1386 float -> file_descr list * file_descr list * file_descr list
1387 Wait until some input/output operations become possible on some chan‐
1389 nels. The three list arguments are, respectively, a set of descriptors
1390 to check for reading (first argument), for writing (second argument),
1391 or for exceptional conditions (third argument). The fourth argument is
1392 the maximal timeout, in seconds; a negative fourth argument means no
1393 timeout (unbounded wait). The result is composed of three sets of de‐
1394 scriptors: those ready for reading (first component), ready for writing
1395 (second component), and over which an exceptional condition is pending
1396 (third component).
1397 Locking
1402 type lock_command =
1403 | F_ULOCK (* Unlock a region
1404 *)
1405 | F_LOCK (* Lock a region for writing, and block if already locked
1406 *)
1407 | F_TLOCK (* Lock a region for writing, or fail if already locked
1408 *)
1409 | F_TEST (* Test a region for other process locks
1410 *)
1411 | F_RLOCK (* Lock a region for reading, and block if already locked
1412 *)
1413 | F_TRLOCK (* Lock a region for reading, or fail if already locked
1414 *)
1415 Commands for Unix.lockf .
1418 val lockf : file_descr -> lock_command -> int -> unit
1422 lockf fd mode len puts a lock on a region of the file opened as fd .
1425 The region starts at the current read/write position for fd (as set by
1426 Unix.lseek ), and extends len bytes forward if len is positive, len
1427 bytes backwards if len is negative, or to the end of the file if len is
1428 zero. A write lock prevents any other process from acquiring a read or
1429 write lock on the region. A read lock prevents any other process from
1430 acquiring a write lock on the region, but lets other processes acquire
1431 read locks on it.
1432 The F_LOCK and F_TLOCK commands attempts to put a write lock on the
1434 specified region. The F_RLOCK and F_TRLOCK commands attempts to put a
1435 read lock on the specified region. If one or several locks put by an‐
1436 other process prevent the current process from acquiring the lock,
1437 F_LOCK and F_RLOCK block until these locks are removed, while F_TLOCK
1438 and F_TRLOCK fail immediately with an exception. The F_ULOCK removes
1439 whatever locks the current process has on the specified region. Fi‐
1440 nally, the F_TEST command tests whether a write lock can be acquired on
1441 the specified region, without actually putting a lock. It returns im‐
1442 mediately if successful, or fails otherwise.
1443 What happens when a process tries to lock a region of a file that is
1445 already locked by the same process depends on the OS. On POSIX-compli‐
1446 ant systems, the second lock operation succeeds and may "promote" the
1447 older lock from read lock to write lock. On Windows, the second lock
1448 operation will block or fail.
1449 Signals
1454 Note: installation of signal handlers is performed via the functions
1455 Sys.signal and Sys.set_signal .
1456 val kill : int -> int -> unit
1458 kill pid signal sends signal number signal to the process with id pid .
1461 On Windows: only the Sys.sigkill signal is emulated.
1463 type sigprocmask_command =
1466 | SIG_SETMASK
1467 | SIG_BLOCK
1468 | SIG_UNBLOCK
1469 val sigprocmask : sigprocmask_command -> int list -> int list
1475 sigprocmask mode sigs changes the set of blocked signals. If mode is
1478 SIG_SETMASK , blocked signals are set to those in the list sigs . If
1479 mode is SIG_BLOCK , the signals in sigs are added to the set of blocked
1480 signals. If mode is SIG_UNBLOCK , the signals in sigs are removed from
1481 the set of blocked signals. sigprocmask returns the set of previously
1482 blocked signals.
1483 When the systhreads version of the Thread module is loaded, this func‐
1485 tion redirects to Thread.sigmask . I.e., sigprocmask only changes the
1486 mask of the current thread.
1487 On Windows: not implemented (no inter-process signals on Windows).
1489 val sigpending : unit -> int list
1493 Return the set of blocked signals that are currently pending.
1495 On Windows: not implemented (no inter-process signals on Windows).
1497 val sigsuspend : int list -> unit
1501 sigsuspend sigs atomically sets the blocked signals to sigs and waits
1504 for a non-ignored, non-blocked signal to be delivered. On return, the
1505 blocked signals are reset to their initial value.
1506 On Windows: not implemented (no inter-process signals on Windows).
1508 val pause : unit -> unit
1512 Wait until a non-ignored, non-blocked signal is delivered.
1514 On Windows: not implemented (no inter-process signals on Windows).
1516 Time functions
1521 type process_times = {
1522 tms_utime : float ; (* User time for the process
1523 *)
1524 tms_stime : float ; (* System time for the process
1525 *)
1526 tms_cutime : float ; (* User time for the children processes
1527 *)
1528 tms_cstime : float ; (* System time for the children processes
1529 *)
1530 }
1531 The execution times (CPU times) of a process.
1534 type tm = {
1537 tm_sec : int ; (* Seconds 0..60
1538 *)
1539 tm_min : int ; (* Minutes 0..59
1540 *)
1541 tm_hour : int ; (* Hours 0..23
1542 *)
1543 tm_mday : int ; (* Day of month 1..31
1544 *)
1545 tm_mon : int ; (* Month of year 0..11
1546 *)
1547 tm_year : int ; (* Year - 1900
1548 *)
1549 tm_wday : int ; (* Day of week (Sunday is 0)
1550 *)
1551 tm_yday : int ; (* Day of year 0..365
1552 *)
1553 tm_isdst : bool ; (* Daylight time savings in effect
1554 *)
1555 }
1556 The type representing wallclock time and calendar date.
1559 val time : unit -> float
1563 Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1565 val gettimeofday : unit -> float
1569 Same as Unix.time , but with resolution better than 1 second.
1571 val gmtime : float -> tm
1575 Convert a time in seconds, as returned by Unix.time , into a date and a
1577 time. Assumes UTC (Coordinated Universal Time), also known as GMT. To
1578 perform the inverse conversion, set the TZ environment variable to
1579 "UTC", use Unix.mktime , and then restore the original value of TZ.
1580 val localtime : float -> tm
1584 Convert a time in seconds, as returned by Unix.time , into a date and a
1586 time. Assumes the local time zone. The function performing the inverse
1587 conversion is Unix.mktime .
1588 val mktime : tm -> float * tm
1592 Convert a date and time, specified by the tm argument, into a time in
1594 seconds, as returned by Unix.time . The tm_isdst , tm_wday and tm_yday
1595 fields of tm are ignored. Also return a normalized copy of the given
1596 tm record, with the tm_wday , tm_yday , and tm_isdst fields recomputed
1597 from the other fields, and the other fields normalized (so that, e.g.,
1598 40 October is changed into 9 November). The tm argument is interpreted
1599 in the local time zone.
1600 val alarm : int -> int
1604 Schedule a SIGALRM signal after the given number of seconds.
1606 On Windows: not implemented.
1608 val sleep : int -> unit
1612 Stop execution for the given number of seconds.
1614 val sleepf : float -> unit
1618 Stop execution for the given number of seconds. Like sleep , but frac‐
1620 tions of seconds are supported.
1621 Since 4.03.0 (4.12.0 in UnixLabels)
1624 val times : unit -> process_times
1628 Return the execution times of the process.
1630 On Windows: partially implemented, will not report timings for child
1632 processes.
1633 val utimes : string -> float -> float -> unit
1637 Set the last access time (second arg) and last modification time (third
1639 arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1640 1, 1970. If both times are 0.0 , the access and last modification
1641 times are both set to the current time.
1642 type interval_timer =
1645 | ITIMER_REAL (* decrements in real time, and sends the signal
1646 SIGALRM when expired.
1647 *)
1648 | ITIMER_VIRTUAL (* decrements in process virtual time, and sends
1649 SIGVTALRM when expired.
1650 *)
1651 | ITIMER_PROF (* (for profiling) decrements both when the process is
1652 running and when the system is running on behalf of the process; it
1653 sends SIGPROF when expired.
1654 *)
1655 The three kinds of interval timers.
1658 type interval_timer_status = {
1661 it_interval : float ; (* Period
1662 *)
1663 it_value : float ; (* Current value of the timer
1664 *)
1665 }
1666 The type describing the status of an interval timer
1669 val getitimer : interval_timer -> interval_timer_status
1673 Return the current status of the given interval timer.
1675 On Windows: not implemented.
1677 val setitimer : interval_timer -> interval_timer_status -> inter‐
1681 val_timer_status
1682 setitimer t s sets the interval timer t and returns its previous sta‐
1685 tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1686 is the time to the next timer expiration; s.it_interval , if nonzero,
1687 specifies a value to be used in reloading it_value when the timer ex‐
1688 pires. Setting s.it_value to zero disables the timer. Setting
1689 s.it_interval to zero causes the timer to be disabled after its next
1690 expiration.
1691 On Windows: not implemented.
1693 User id, group id
1698 val getuid : unit -> int
1699 Return the user id of the user executing the process.
1701 On Windows: always returns 1 .
1703 val geteuid : unit -> int
1707 Return the effective user id under which the process runs.
1709 On Windows: always returns 1 .
1711 val setuid : int -> unit
1715 Set the real user id and effective user id for the process.
1717 On Windows: not implemented.
1719 val getgid : unit -> int
1723 Return the group id of the user executing the process.
1725 On Windows: always returns 1 .
1727 val getegid : unit -> int
1731 Return the effective group id under which the process runs.
1733 On Windows: always returns 1 .
1735 val setgid : int -> unit
1739 Set the real group id and effective group id for the process.
1741 On Windows: not implemented.
1743 val getgroups : unit -> int array
1747 Return the list of groups to which the user executing the process be‐
1749 longs.
1750 On Windows: always returns [|1|] .
1752 val setgroups : int array -> unit
1756 setgroups groups sets the supplementary group IDs for the calling
1759 process. Appropriate privileges are required.
1760 On Windows: not implemented.
1762 val initgroups : string -> int -> unit
1766 initgroups user group initializes the group access list by reading the
1769 group database /etc/group and using all groups of which user is a mem‐
1770 ber. The additional group group is also added to the list.
1771 On Windows: not implemented.
1773 type passwd_entry = {
1776 pw_name : string ;
1777 pw_passwd : string ;
1778 pw_uid : int ;
1779 pw_gid : int ;
1780 pw_gecos : string ;
1781 pw_dir : string ;
1782 pw_shell : string ;
1783 }
1784 Structure of entries in the passwd database.
1787 type group_entry = {
1790 gr_name : string ;
1791 gr_passwd : string ;
1792 gr_gid : int ;
1793 gr_mem : string array ;
1794 }
1795 Structure of entries in the groups database.
1798 val getlogin : unit -> string
1802 Return the login name of the user executing the process.
1804 val getpwnam : string -> passwd_entry
1808 Find an entry in passwd with the given name.
1810 Raises Not_found if no such entry exists, or always on Windows.
1813 val getgrnam : string -> group_entry
1817 Find an entry in group with the given name.
1819 Raises Not_found if no such entry exists, or always on Windows.
1822 val getpwuid : int -> passwd_entry
1826 Find an entry in passwd with the given user id.
1828 Raises Not_found if no such entry exists, or always on Windows.
1831 val getgrgid : int -> group_entry
1835 Find an entry in group with the given group id.
1837 Raises Not_found if no such entry exists, or always on Windows.
1840 Internet addresses
1845 type inet_addr
1846 The abstract type of Internet addresses.
1849 val inet_addr_of_string : string -> inet_addr
1853 Conversion from the printable representation of an Internet address to
1855 its internal representation. The argument string consists of 4 numbers
1856 separated by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up to
1857 8 numbers separated by colons for IPv6 addresses.
1858 Raises Failure when given a string that does not match these formats.
1861 val string_of_inet_addr : inet_addr -> string
1865 Return the printable representation of the given Internet address. See
1867 Unix.inet_addr_of_string for a description of the printable representa‐
1868 tion.
1869 val inet_addr_any : inet_addr
1873 A special IPv4 address, for use only with bind , representing all the
1875 Internet addresses that the host machine possesses.
1876 val inet_addr_loopback : inet_addr
1880 A special IPv4 address representing the host machine ( 127.0.0.1 ).
1882 val inet6_addr_any : inet_addr
1886 A special IPv6 address, for use only with bind , representing all the
1888 Internet addresses that the host machine possesses.
1889 val inet6_addr_loopback : inet_addr
1893 A special IPv6 address representing the host machine ( ::1 ).
1895 val is_inet6_addr : inet_addr -> bool
1899 Whether the given inet_addr is an IPv6 address.
1901 Since 4.12.0
1904 Sockets
1909 type socket_domain =
1910 | PF_UNIX (* Unix domain
1911 *)
1912 | PF_INET (* Internet domain (IPv4)
1913 *)
1914 | PF_INET6 (* Internet domain (IPv6)
1915 *)
1916 The type of socket domains. Not all platforms support IPv6 sockets
1919 (type PF_INET6 ).
1920 On Windows: PF_UNIX not implemented.
1922 type socket_type =
1925 | SOCK_STREAM (* Stream socket
1926 *)
1927 | SOCK_DGRAM (* Datagram socket
1928 *)
1929 | SOCK_RAW (* Raw socket
1930 *)
1931 | SOCK_SEQPACKET (* Sequenced packets socket
1932 *)
1933 The type of socket kinds, specifying the semantics of communications.
1936 SOCK_SEQPACKET is included for completeness, but is rarely supported by
1937 the OS, and needs system calls that are not available in this library.
1938 type sockaddr =
1941 | ADDR_UNIX of string
1942 | ADDR_INET of inet_addr * int
1943 The type of socket addresses. ADDR_UNIX name is a socket address in
1946 the Unix domain; name is a file name in the file system.
1947 ADDR_INET(addr,port) is a socket address in the Internet domain; addr
1948 is the Internet address of the machine, and port is the port number.
1949 val socket : ?cloexec:bool -> socket_domain -> socket_type -> int ->
1953 file_descr
1954 Create a new socket in the given domain, and with the given kind. The
1956 third argument is the protocol type; 0 selects the default protocol for
1957 that kind of sockets. See Unix.set_close_on_exec for documentation on
1958 the cloexec optional argument.
1959 val domain_of_sockaddr : sockaddr -> socket_domain
1963 Return the socket domain adequate for the given socket address.
1965 val socketpair : ?cloexec:bool -> socket_domain -> socket_type -> int
1969 -> file_descr * file_descr
1970 Create a pair of unnamed sockets, connected together. See
1972 Unix.set_close_on_exec for documentation on the cloexec optional argu‐
1973 ment.
1974 val accept : ?cloexec:bool -> file_descr -> file_descr * sockaddr
1978 Accept connections on the given socket. The returned descriptor is a
1980 socket connected to the client; the returned address is the address of
1981 the connecting client. See Unix.set_close_on_exec for documentation on
1982 the cloexec optional argument.
1983 val bind : file_descr -> sockaddr -> unit
1987 Bind a socket to an address.
1989 val connect : file_descr -> sockaddr -> unit
1993 Connect a socket to an address.
1995 val listen : file_descr -> int -> unit
1999 Set up a socket for receiving connection requests. The integer argument
2001 is the maximal number of pending requests.
2002 type shutdown_command =
2005 | SHUTDOWN_RECEIVE (* Close for receiving
2006 *)
2007 | SHUTDOWN_SEND (* Close for sending
2008 *)
2009 | SHUTDOWN_ALL (* Close both
2010 *)
2011 The type of commands for shutdown .
2014 val shutdown : file_descr -> shutdown_command -> unit
2018 Shutdown a socket connection. SHUTDOWN_SEND as second argument causes
2020 reads on the other end of the connection to return an end-of-file con‐
2021 dition. SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
2022 tion to return a closed pipe condition ( SIGPIPE signal).
2023 val getsockname : file_descr -> sockaddr
2027 Return the address of the given socket.
2029 val getpeername : file_descr -> sockaddr
2033 Return the address of the host connected to the given socket.
2035 type msg_flag =
2038 | MSG_OOB
2039 | MSG_DONTROUTE
2040 | MSG_PEEK
2041 The flags for Unix.recv , Unix.recvfrom , Unix.send and Unix.sendto .
2044 val recv : file_descr -> bytes -> int -> int -> msg_flag list -> int
2048 Receive data from a connected socket.
2050 val recvfrom : file_descr -> bytes -> int -> int -> msg_flag list ->
2054 int * sockaddr
2055 Receive data from an unconnected socket.
2057 val send : file_descr -> bytes -> int -> int -> msg_flag list -> int
2061 Send data over a connected socket.
2063 val send_substring : file_descr -> string -> int -> int -> msg_flag
2067 list -> int
2068 Same as send , but take the data from a string instead of a byte se‐
2070 quence.
2071 Since 4.02.0
2074 val sendto : file_descr -> bytes -> int -> int -> msg_flag list ->
2078 sockaddr -> int
2079 Send data over an unconnected socket.
2081 val sendto_substring : file_descr -> string -> int -> int -> msg_flag
2085 list -> sockaddr -> int
2086 Same as sendto , but take the data from a string instead of a byte se‐
2088 quence.
2089 Since 4.02.0
2092 Socket options
2097 type socket_bool_option =
2098 | SO_DEBUG (* Record debugging information
2099 *)
2100 | SO_BROADCAST (* Permit sending of broadcast messages
2101 *)
2102 | SO_REUSEADDR (* Allow reuse of local addresses for bind
2103 *)
2104 | SO_KEEPALIVE (* Keep connection active
2105 *)
2106 | SO_DONTROUTE (* Bypass the standard routing algorithms
2107 *)
2108 | SO_OOBINLINE (* Leave out-of-band data in line
2109 *)
2110 | SO_ACCEPTCONN (* Report whether socket listening is enabled
2111 *)
2112 | TCP_NODELAY (* Control the Nagle algorithm for TCP sockets
2113 *)
2114 | IPV6_ONLY (* Forbid binding an IPv6 socket to an IPv4 address
2115 *)
2116 | SO_REUSEPORT (* Allow reuse of address and port bindings
2117 *)
2118 The socket options that can be consulted with Unix.getsockopt and modi‐
2121 fied with Unix.setsockopt . These options have a boolean ( true /
2122 false ) value.
2123 type socket_int_option =
2126 | SO_SNDBUF (* Size of send buffer
2127 *)
2128 | SO_RCVBUF (* Size of received buffer
2129 *)
2130 | SO_ERROR (* Deprecated. Use Unix.getsockopt_error instead.
2131 *)
2132 | SO_TYPE (* Report the socket type
2133 *)
2134 | SO_RCVLOWAT (* Minimum number of bytes to process for input opera‐
2135 tions
2136 *)
2137 | SO_SNDLOWAT (* Minimum number of bytes to process for output opera‐
2138 tions
2139 *)
2140 The socket options that can be consulted with Unix.getsockopt_int and
2143 modified with Unix.setsockopt_int . These options have an integer
2144 value.
2145 type socket_optint_option =
2148 | SO_LINGER (* Whether to linger on closed connections that have data
2149 present, and for how long (in seconds)
2150 *)
2151 The socket options that can be consulted with Unix.getsockopt_optint
2154 and modified with Unix.setsockopt_optint . These options have a value
2155 of type int option , with None meaning ``disabled''.
2156 type socket_float_option =
2159 | SO_RCVTIMEO (* Timeout for input operations
2160 *)
2161 | SO_SNDTIMEO (* Timeout for output operations
2162 *)
2163 The socket options that can be consulted with Unix.getsockopt_float and
2166 modified with Unix.setsockopt_float . These options have a float‐
2167 ing-point value representing a time in seconds. The value 0 means in‐
2168 finite timeout.
2169 val getsockopt : file_descr -> socket_bool_option -> bool
2173 Return the current status of a boolean-valued option in the given
2175 socket.
2176 val setsockopt : file_descr -> socket_bool_option -> bool -> unit
2180 Set or clear a boolean-valued option in the given socket.
2182 val getsockopt_int : file_descr -> socket_int_option -> int
2186 Same as Unix.getsockopt for an integer-valued socket option.
2188 val setsockopt_int : file_descr -> socket_int_option -> int -> unit
2192 Same as Unix.setsockopt for an integer-valued socket option.
2194 val getsockopt_optint : file_descr -> socket_optint_option -> int op‐
2198 tion
2199 Same as Unix.getsockopt for a socket option whose value is an int op‐
2201 tion .
2202 val setsockopt_optint : file_descr -> socket_optint_option -> int op‐
2206 tion -> unit
2207 Same as Unix.setsockopt for a socket option whose value is an int op‐
2209 tion .
2210 val getsockopt_float : file_descr -> socket_float_option -> float
2214 Same as Unix.getsockopt for a socket option whose value is a float‐
2216 ing-point number.
2217 val setsockopt_float : file_descr -> socket_float_option -> float ->
2221 unit
2222 Same as Unix.setsockopt for a socket option whose value is a float‐
2224 ing-point number.
2225 val getsockopt_error : file_descr -> error option
2229 Return the error condition associated with the given socket, and clear
2231 it.
2232 High-level network connection functions
2237 val open_connection : sockaddr -> in_channel * out_channel
2238 Connect to a server at the given address. Return a pair of buffered
2240 channels connected to the server. Remember to call flush on the output
2241 channel at the right times to ensure correct synchronization.
2242 The two channels returned by open_connection share a descriptor to a
2244 socket. Therefore, when the connection is over, you should call
2245 close_out on the output channel, which will also close the underlying
2246 socket. Do not call close_in on the input channel; it will be col‐
2247 lected by the GC eventually.
2248 val shutdown_connection : in_channel -> unit
2252 ``Shut down'' a connection established with Unix.open_connection ; that
2254 is, transmit an end-of-file condition to the server reading on the
2255 other side of the connection. This does not close the socket and the
2256 channels used by the connection. See Unix.open_connection for how to
2257 close them once the connection is over.
2258 val establish_server : (in_channel -> out_channel -> unit) -> sockaddr
2262 -> unit
2263 Establish a server on the given address. The function given as first
2265 argument is called for each connection with two buffered channels con‐
2266 nected to the client. A new process is created for each connection. The
2267 function Unix.establish_server never returns normally.
2268 The two channels given to the function share a descriptor to a socket.
2270 The function does not need to close the channels, since this occurs au‐
2271 tomatically when the function returns. If the function prefers ex‐
2272 plicit closing, it should close the output channel using close_out and
2273 leave the input channel unclosed, for reasons explained in
2274 Unix.in_channel_of_descr .
2275 On Windows: not implemented (use threads).
2277 Host and protocol databases
2282 type host_entry = {
2283 h_name : string ;
2284 h_aliases : string array ;
2285 h_addrtype : socket_domain ;
2286 h_addr_list : inet_addr array ;
2287 }
2288 Structure of entries in the hosts database.
2291 type protocol_entry = {
2294 p_name : string ;
2295 p_aliases : string array ;
2296 p_proto : int ;
2297 }
2298 Structure of entries in the protocols database.
2301 type service_entry = {
2304 s_name : string ;
2305 s_aliases : string array ;
2306 s_port : int ;
2307 s_proto : string ;
2308 }
2309 Structure of entries in the services database.
2312 val gethostname : unit -> string
2316 Return the name of the local host.
2318 val gethostbyname : string -> host_entry
2322 Find an entry in hosts with the given name.
2324 Raises Not_found if no such entry exists.
2327 val gethostbyaddr : inet_addr -> host_entry
2331 Find an entry in hosts with the given address.
2333 Raises Not_found if no such entry exists.
2336 val getprotobyname : string -> protocol_entry
2340 Find an entry in protocols with the given name.
2342 Raises Not_found if no such entry exists.
2345 val getprotobynumber : int -> protocol_entry
2349 Find an entry in protocols with the given protocol number.
2351 Raises Not_found if no such entry exists.
2354 val getservbyname : string -> string -> service_entry
2358 Find an entry in services with the given name.
2360 Raises Not_found if no such entry exists.
2363 val getservbyport : int -> string -> service_entry
2367 Find an entry in services with the given service number.
2369 Raises Not_found if no such entry exists.
2372 type addr_info = {
2375 ai_family : socket_domain ; (* Socket domain
2376 *)
2377 ai_socktype : socket_type ; (* Socket type
2378 *)
2379 ai_protocol : int ; (* Socket protocol number
2380 *)
2381 ai_addr : sockaddr ; (* Address
2382 *)
2383 ai_canonname : string ; (* Canonical host name
2384 *)
2385 }
2386 Address information returned by Unix.getaddrinfo .
2389 type getaddrinfo_option =
2392 | AI_FAMILY of socket_domain
2393 (* Impose the given socket domain
2394 *)
2395 | AI_SOCKTYPE of socket_type
2396 (* Impose the given socket type
2397 *)
2398 | AI_PROTOCOL of int
2399 (* Impose the given protocol
2400 *)
2401 | AI_NUMERICHOST (* Do not call name resolver, expect numeric IP ad‐
2402 dress
2403 *)
2404 | AI_CANONNAME (* Fill the ai_canonname field of the result
2405 *)
2406 | AI_PASSIVE (* Set address to ``any'' address for use with Unix.bind
2407 *)
2409 Options to Unix.getaddrinfo .
2412 val getaddrinfo : string -> string -> getaddrinfo_option list ->
2416 addr_info list
2417 getaddrinfo host service opts returns a list of Unix.addr_info records
2420 describing socket parameters and addresses suitable for communicating
2421 with the given host and service. The empty list is returned if the
2422 host or service names are unknown, or the constraints expressed in opts
2423 cannot be satisfied.
2424 host is either a host name or the string representation of an IP ad‐
2427 dress. host can be given as the empty string; in this case, the
2428 ``any'' address or the ``loopback'' address are used, depending whether
2429 opts contains AI_PASSIVE . service is either a service name or the
2430 string representation of a port number. service can be given as the
2431 empty string; in this case, the port field of the returned addresses is
2432 set to 0. opts is a possibly empty list of options that allows the
2433 caller to force a particular socket domain (e.g. IPv6 only or IPv4
2434 only) or a particular socket type (e.g. TCP only or UDP only).
2435 type name_info = {
2438 ni_hostname : string ; (* Name or IP address of host
2439 *)
2440 ni_service : string ; (* Name of service or port number
2441 *)
2442 }
2443 Host and service information returned by Unix.getnameinfo .
2446 type getnameinfo_option =
2449 | NI_NOFQDN (* Do not qualify local host names
2450 *)
2451 | NI_NUMERICHOST (* Always return host as IP address
2452 *)
2453 | NI_NAMEREQD (* Fail if host name cannot be determined
2454 *)
2455 | NI_NUMERICSERV (* Always return service as port number
2456 *)
2457 | NI_DGRAM (* Consider the service as UDP-based instead of the de‐
2458 fault TCP
2459 *)
2460 Options to Unix.getnameinfo .
2463 val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
2467 getnameinfo addr opts returns the host name and service name corre‐
2470 sponding to the socket address addr . opts is a possibly empty list of
2471 options that governs how these names are obtained.
2472 Raises Not_found if an error occurs.
2475 Terminal interface
2480 The following functions implement the POSIX standard terminal inter‐
2481 face. They provide control over asynchronous communication ports and
2482 pseudo-terminals. Refer to the termios man page for a complete descrip‐
2483 tion.
2484 type terminal_io = {
2486 mutable c_ignbrk : bool ; (* Ignore the break condition.
2488 *)
2489 mutable c_brkint : bool ; (* Signal interrupt on break condition.
2491 *)
2492 mutable c_ignpar : bool ; (* Ignore characters with parity errors.
2494 *)
2495 mutable c_parmrk : bool ; (* Mark parity errors.
2497 *)
2498 mutable c_inpck : bool ; (* Enable parity check on input.
2500 *)
2501 mutable c_istrip : bool ; (* Strip 8th bit on input characters.
2503 *)
2504 mutable c_inlcr : bool ; (* Map NL to CR on input.
2506 *)
2507 mutable c_igncr : bool ; (* Ignore CR on input.
2509 *)
2510 mutable c_icrnl : bool ; (* Map CR to NL on input.
2512 *)
2513 mutable c_ixon : bool ; (* Recognize XON/XOFF characters on input.
2515 *)
2516 mutable c_ixoff : bool ; (* Emit XON/XOFF chars to control input flow.
2518 *)
2519 mutable c_opost : bool ; (* Enable output processing.
2521 *)
2522 mutable c_obaud : int ; (* Output baud rate (0 means close connec‐
2524 tion).
2525 *)
2526 mutable c_ibaud : int ; (* Input baud rate.
2528 *)
2529 mutable c_csize : int ; (* Number of bits per character (5-8).
2531 *)
2532 mutable c_cstopb : int ; (* Number of stop bits (1-2).
2534 *)
2535 mutable c_cread : bool ; (* Reception is enabled.
2537 *)
2538 mutable c_parenb : bool ; (* Enable parity generation and detection.
2540 *)
2541 mutable c_parodd : bool ; (* Specify odd parity instead of even.
2543 *)
2544 mutable c_hupcl : bool ; (* Hang up on last close.
2546 *)
2547 mutable c_clocal : bool ; (* Ignore modem status lines.
2549 *)
2550 mutable c_isig : bool ; (* Generate signal on INTR, QUIT, SUSP.
2552 *)
2553 mutable c_icanon : bool ; (* Enable canonical processing (line buffer‐
2555 ing and editing)
2556 *)
2557 mutable c_noflsh : bool ; (* Disable flush after INTR, QUIT, SUSP.
2559 *)
2560 mutable c_echo : bool ; (* Echo input characters.
2562 *)
2563 mutable c_echoe : bool ; (* Echo ERASE (to erase previous character).
2565 *)
2566 mutable c_echok : bool ; (* Echo KILL (to erase the current line).
2568 *)
2569 mutable c_echonl : bool ; (* Echo NL even if c_echo is not set.
2571 *)
2572 mutable c_vintr : char ; (* Interrupt character (usually ctrl-C).
2574 *)
2575 mutable c_vquit : char ; (* Quit character (usually ctrl-\).
2577 *)
2578 mutable c_verase : char ; (* Erase character (usually DEL or ctrl-H).
2580 *)
2581 mutable c_vkill : char ; (* Kill line character (usually ctrl-U).
2583 *)
2584 mutable c_veof : char ; (* End-of-file character (usually ctrl-D).
2586 *)
2587 mutable c_veol : char ; (* Alternate end-of-line char. (usually none).
2589 *)
2590 mutable c_vmin : int ; (* Minimum number of characters to read before
2592 the read request is satisfied.
2593 *)
2594 mutable c_vtime : int ; (* Maximum read wait (in 0.1s units).
2596 *)
2597 mutable c_vstart : char ; (* Start character (usually ctrl-Q).
2599 *)
2600 mutable c_vstop : char ; (* Stop character (usually ctrl-S).
2602 *)
2603 }
2604 val tcgetattr : file_descr -> terminal_io
2610 Return the status of the terminal referred to by the given file de‐
2612 scriptor.
2613 On Windows: not implemented.
2615 type setattr_when =
2618 | TCSANOW
2619 | TCSADRAIN
2620 | TCSAFLUSH
2621 val tcsetattr : file_descr -> setattr_when -> terminal_io -> unit
2627 Set the status of the terminal referred to by the given file descrip‐
2629 tor. The second argument indicates when the status change takes place:
2630 immediately ( TCSANOW ), when all pending output has been transmitted (
2631 TCSADRAIN ), or after flushing all input that has been received but not
2632 read ( TCSAFLUSH ). TCSADRAIN is recommended when changing the output
2633 parameters; TCSAFLUSH , when changing the input parameters.
2634 On Windows: not implemented.
2636 val tcsendbreak : file_descr -> int -> unit
2640 Send a break condition on the given file descriptor. The second argu‐
2642 ment is the duration of the break, in 0.1s units; 0 means standard du‐
2643 ration (0.25s).
2644 On Windows: not implemented.
2646 val tcdrain : file_descr -> unit
2650 Waits until all output written on the given file descriptor has been
2652 transmitted.
2653 On Windows: not implemented.
2655 type flush_queue =
2658 | TCIFLUSH
2659 | TCOFLUSH
2660 | TCIOFLUSH
2661 val tcflush : file_descr -> flush_queue -> unit
2667 Discard data written on the given file descriptor but not yet transmit‐
2669 ted, or data received but not yet read, depending on the second argu‐
2670 ment: TCIFLUSH flushes data received but not read, TCOFLUSH flushes
2671 data written but not transmitted, and TCIOFLUSH flushes both.
2672 On Windows: not implemented.
2674 type flow_action =
2677 | TCOOFF
2678 | TCOON
2679 | TCIOFF
2680 | TCION
2681 val tcflow : file_descr -> flow_action -> unit
2687 Suspend or restart reception or transmission of data on the given file
2689 descriptor, depending on the second argument: TCOOFF suspends output,
2690 TCOON restarts output, TCIOFF transmits a STOP character to suspend in‐
2691 put, and TCION transmits a START character to restart input.
2692 On Windows: not implemented.
2694 val setsid : unit -> int
2698 Put the calling process in a new session and detach it from its con‐
2700 trolling terminal.
2701 On Windows: not implemented.
2703OCamldoc 2022-02-04 Unix(3)