libreplace: fix coverity ID 517 - untangle close from open in test/os2_delete.c
[jelmer/samba4-debian.git] / prog_guide.txt
index df03ecac22d5c234c32fd32f35d727e825f1f985..bba58b31b3b9350ba0e0d9e56b32d67e31710a87 100644 (file)
@@ -1,7 +1,7 @@
-THIS IS INCOMPLETE! I'M ONLY COMMITING IT IN ORDER TO SOLICIT COMMENTS
-FROM A FEW PEOPLE. DON'T TAKE THIS AS THE FINAL VERSION YET.
 
 
+THIS IS INCOMPLETE! I'M ONLY COMMITING IT IN ORDER TO SOLICIT COMMENTS
+FROM A FEW PEOPLE. DON'T TAKE THIS AS THE FINAL VERSION YET.
 
 
 Samba4 Programming Guide
@@ -58,11 +58,11 @@ Static and Global Data
 
 The basic rule is "avoid static and global data like the plague". What
 do I mean by static data? The way to tell if you have static data in a
-file is to use the "size" utility in Linux. For example if we run:
+file is to use the "size" utility in Linux. For example if we run::
 
   size libcli/raw/*.o
 
-in Samba4 then you get the following:
+in Samba4 then you get the following::
 
    text    data     bss     dec     hex filename
    2015       0       0    2015     7df libcli/raw/clikrb5.o
@@ -91,7 +91,7 @@ notice that the "data" and "bss" columns are all zero? That is
 good. If there are any non-zero values in data or bss then that
 indicates static data and is bad (as a rule of thumb).
 
-Lets compare that result to the equivalent in Samba3:
+Lets compare that result to the equivalent in Samba3::
 
    text    data     bss     dec     hex filename
    3978       0       0    3978     f8a libsmb/asn1.o
@@ -142,10 +142,11 @@ notice all of the non-zero data and bss elements? Every bit of that
 data is a bug waiting to happen.
 
 Static data is evil as it has the following consequences:
- - it makes code much less likely to be thread-safe
- - it makes code much less likely to be recursion-safe
- - it leads to subtle side effects when the same code is called from
-   multiple places
+- it makes code much less likely to be thread-safe
+- it makes code much less likely to be recursion-safe
+- it leads to subtle side effects when the same code is called from
+  multiple places
+- doesn't play well with shared libraries or plugins
 
 Static data is particularly evil in library code (such as our internal
 smb and rpc libraries). If you can get rid of all static data in
@@ -190,43 +191,11 @@ in the data and bss columns in "size" anyway (it will be included in
 "text"). So you can have constant tables of protocol data.
 
 
-Memory Contexts
----------------
+How to use talloc
+-----------------
 
-We introduced the talloc() system for memory contexts during the 2.2
-development cycle and it has been a great success. It has greatly
-simplified a lot of our code, particularly with regard to error
-handling. 
-
-In Samba4 we use talloc even more extensively to give us much finer
-grained memory management. The really important thing to remember
-about talloc in Samba4 is:
-
-  "don't just use the first talloc context that comes to hand - use
-  the RIGHT talloc context"
-
-Just using the first talloc context that comes to hand is probably the
-most common systematic bug I have seen so far from programmers that
-have worked on the Samba4 code base. The reason this is vital is that
-different talloc contexts have vastly different lifetimes, so if you
-use a talloc context that has a long lifetime (such as one associated
-with a tree connection) for data that is very short lived (such as
-parsing an individual packet) then you have just introduced a huge
-memory leak.
-
-In fact, it is quite common that the correct thing to do is to create
-a new talloc context for some little function and then destroy it when
-you are done. That will give you a memory context that has exactly the
-right lifetime.
-
-You should also go and look at a new talloc function in Samba4 called
-talloc_steal(). By using talloc_steal() you can move a lump of memory
-from one memory context to another without copying the data. This
-should be used when a backend function (such as a packet parser)
-produces a result as a lump of talloc memory and you need to keep it
-around for a longer lifetime than the talloc context it is in. You
-just "steal" the memory from the short-lived context, putting it into
-your long lived context.
+Please see the separate document, source/lib/talloc/talloc_guide.txt
+You _must_ read this if you want to program in Samba4.
 
 
 Interface Structures
@@ -239,7 +208,7 @@ an idea of what I am talking about.
 In Samba3 many of the core wire structures in the SMB protocol were
 never explicitly defined in Samba. Instead, our parse and generation
 functions just worked directly with wire buffers. The biggest problem
-with this is that is tied our parse code with out "business logic"
+with this is that is tied our parse code with our "business logic"
 much too closely, which meant the code got extremely confusing to
 read.
 
@@ -264,27 +233,27 @@ msrpc code from Samba3", and while to some extent this is true there
 are extremely important differences in the approach that are worth
 pointing out.
 
-In the Samba3 msrpc code we used explicit parse strucrures for all
+In the Samba3 msrpc code we used explicit parse structures for all
 msrpc functions. The problem is that we didn't just put all of the
 real variables in these structures, we also put in all the artifacts
 as well. A good example is the security descriptor strucrure that
-looks like this in Samba3:
+looks like this in Samba3::
 
-typedef struct security_descriptor_info
-{
-       uint16 revision; 
-       uint16 type;    
+       typedef struct security_descriptor_info
+       {
+               uint16 revision; 
+               uint16 type;    
 
-       uint32 off_owner_sid;
-       uint32 off_grp_sid;
-       uint32 off_sacl;
-       uint32 off_dacl;
+               uint32 off_owner_sid;
+               uint32 off_grp_sid;
+               uint32 off_sacl;
+               uint32 off_dacl;
 
-       SEC_ACL *dacl;
-       SEC_ACL *sacl;
-       DOM_SID *owner_sid; 
-       DOM_SID *grp_sid;
-} SEC_DESC;
+               SEC_ACL *dacl;
+               SEC_ACL *sacl;
+               DOM_SID *owner_sid; 
+               DOM_SID *grp_sid;
+       } SEC_DESC;
 
 The problem with this structure is all the off_* variables. Those are
 not part of the interface, and do not appear in any real descriptions
@@ -295,7 +264,7 @@ parser where to find the following four variables, but they should
 *NOT* be in the interface structure.
 
 In Samba3 there were unwritten rules about which variables in a
-strucrure a high level caller has to fill in and which ones are filled
+structure a high level caller has to fill in and which ones are filled
 in by the marshalling code. In Samba4 those rules are gone, because
 the redundent artifact variables are gone. The high level caller just
 sets up the real variables and the marshalling code worries about
@@ -332,11 +301,11 @@ just about everywhere.
 
 The first aspect of the async design to look at is the SMB client
 library. Lets take a look at the following three functions in
-libcli/raw/rawfile.c:
+libcli/raw/rawfile.c::
 
-struct cli_request *smb_raw_seek_send(struct cli_tree *tree, struct smb_seek *parms);
-NTSTATUS smb_raw_seek_recv(struct cli_request *req, struct smb_seek *parms);
-NTSTATUS smb_raw_seek(struct cli_tree *tree, struct smb_seek *parms);
+       struct cli_request *smb_raw_seek_send(struct cli_tree *tree, struct smb_seek *parms);
+       NTSTATUS smb_raw_seek_recv(struct cli_request *req, struct smb_seek *parms);
+       NTSTATUS smb_raw_seek(struct cli_tree *tree, struct smb_seek *parms);
 
 Go and read them now then come back.
 
@@ -358,7 +327,7 @@ one called smb_raw_XXXX(). That just calls the first two in order, and
 blocks waiting for the reply. 
 
 But what if you want to be called when the reply comes in? Yes, thats
-possible. You can do things like this:
+possible. You can do things like this::
 
     struct cli_request *req;
 
@@ -405,7 +374,7 @@ to just like in Samba3, but it also has the option of answering the
 request asynchronously. The only backend that currently does this is
 the CIFS backend, but I hope the other backends will soon do this to.
 
-To make this work you need to do things like this in the backend:
+To make this work you need to do things like this in the backend::
 
   req->control_flags |= REQ_CONTROL_ASYNC;
 
@@ -427,7 +396,7 @@ function, so smbd has a _send() function and the parse function for
 each SMB.
 
 As an example go and have a look at reply_getatr_send() and
-reply_getatr() in smbd/reply.c. Read them? Good.
+reply_getatr() in smb_server/reply.c. Read them? Good.
 
 Notice that reply_getatr() sets up the req->async structure to contain
 the send function. Thats how the backend gets to do an async reply, it
@@ -481,7 +450,7 @@ and read it. Yes, that means you!).
 Notice the union? That's how Samba4 allows a single NTVFS backend
 interface to handle the several different ways of doing a write
 operation in the SMB protocol. Now lets look at one section of that
-union:
+union::
 
        /* SMBwriteX interface */
        struct {
@@ -504,7 +473,7 @@ union:
 see the "in" and "out" sections? The "in" section is for parameters
 that the SMB client sends on the wire as part of the request. The smbd
 front end parse code parses the wire request and fills in all those
-parameters. It then calls the NTVFS interface which looks like this:
+parameters. It then calls the NTVFS interface which looks like this::
 
   NTSTATUS (*write)(struct request_context *req, union smb_write *io);
 
@@ -558,45 +527,68 @@ string.
 
 The format is:
 
-  TRANSPORT:host:[flags]
+  TRANSPORT:host[flags]
 
 where TRANSPORT is either ncacn_np for SMB or ncacn_ip_tcp for RPC/TCP
 
-"host" is an IP or hostname or netbios name
+"host" is an IP or hostname or netbios name. If the binding string 
+identifies the server side of an endpoint, "host" may be an empty 
+string.
 
-"flags" must start with the pipe name if using the ncacn_np transport
-
-The ncacn_ip_tcp can take an integer flag giving the TCP port
-number. It must be the first flag if given.
+"flags" can include a SMB pipe name if using the ncacn_np transport or
+a TCP port number if using the ncacn_ip_tcp transport, otherwise they
+will be auto-determined.
 
 other recognised flags are:
 
-  sign : enable ntlmssp signing
-  seal : enable ntlmssp sealing
-  validate: enable the NDR validator
-  bigendian: use bigendian RPC
+  sign      : enable ntlmssp signing
+  seal      : enable ntlmssp sealing
+  spnego    : use SPNEGO instead of NTLMSSP authentication
+  krb5      : use KRB5 instead of NTLMSSP authentication
+  connect   : enable rpc connect level auth (auth, but no sign or seal)
+  validate  : enable the NDR validator
+  print     : enable debugging of the packets
+  bigendian : use bigendian RPC
+  padcheck  : check reply data for non-zero pad bytes
 
 
-For example, these all connect to the samr pipe:
+Here are some examples:
 
    ncacn_np:myserver
-   ncacn_np:myserver:samr
-   ncacn_np:myserver:samr,seal
-   ncacn_np:myserver:\pipe\samr
-   ncacn_np:myserver:/pipe/samr
    ncacn_np:myserver[samr]
    ncacn_np:myserver[\pipe\samr]
    ncacn_np:myserver[/pipe/samr]
-   ncacn_np:myserver:[samr,sign]
-   ncacn_np:myserver:[\pipe\samr,sign,seal,bigendian]
-   ncacn_np:myserver:[/pipe/samr,seal]
-
+   ncacn_np:myserver[samr,sign,print]
+   ncacn_np:myserver[sign,spnego]
+   ncacn_np:myserver[\pipe\samr,sign,seal,bigendian]
+   ncacn_np:myserver[/pipe/samr,seal,validate]
+   ncacn_np:
+   ncacn_np:[/pipe/samr]
    ncacn_ip_tcp:myserver
-   ncacn_ip_tcp:myserver:1024
    ncacn_ip_tcp:myserver[1024]
-   ncacn_ip_tcp:myserver:[1024,sign,seal]
+   ncacn_ip_tcp:myserver[sign,seal]
+   ncacn_ip_tcp:myserver[spnego,seal]
+
 
+IDEA: Maybe extend UNC names like this?
 
+ smbclient //server/share
+ smbclient //server/share[sign,seal,spnego]
+
+DCERPC Handles
+--------------
+The various handles that are used in the RPC servers should be created and 
+fetch using the dcesrv_handle_* functions.
+
+Use dcesrv_handle_new(struct dcesrv_connection *, uint8 handle_type) to obtain 
+a new handle of the specified type. Handle types are unique within each 
+pipe.
+
+The handle can later be fetched again using
+struct dcesrv_handle *dcesrv_handle_fetch(struct dcesrv_connection *dce_conn, struct policy_handle *p, uint8 handle_type)
+and destroyed by dcesrv_handle_destroy(struct dcesrv_handle *).
+
+User data should be stored in the 'data' member of the dcesrv_handle struct.
 
 
 MSRPC
@@ -615,8 +607,6 @@ MSRPC
  - msrpc
 
 
-- use _p talloc varients
-
 don't zero structures! avoid ZERO_STRUCT() and talloc_zero()
 
 
@@ -626,8 +616,6 @@ put in full UNC path in tconx
 
 test timezone handling by using a server in different zone from client
 
-don't just use any old TALLOC_CTX, use the right one!
-
 do {} while (0) system
 
 NT_STATUS_IS_OK() is NOT the opposite of NT_STATUS_IS_ERR()
@@ -635,8 +623,6 @@ NT_STATUS_IS_OK() is NOT the opposite of NT_STATUS_IS_ERR()
 need to implement secondary parts of trans2 and nttrans in server and
 client
 
-add talloc_steal() to move a talloc ptr from one pool to another
-
 document access_mask in openx reply
 
 check all capabilities and flag1, flag2 fields (eg. EAs)
@@ -736,3 +722,68 @@ docs
 
   conference paper
   developer docs
+
+svn instructions
+
+Ideas
+-----
+
+ - store all config in config.ldb
+
+ - load from smb.conf if modtime changes
+
+ - dump full system config with ldbsearch
+
+ - will need the ability to form a ldif difference file
+
+ - advanced web admin via a web ldb editor
+
+ - normal web admin via web forms -> ldif
+
+ - config.ldb will replace smb.conf, secrets.tdb, shares.tdb etc
+
+ - subsystems in smbd will load config parameters for a share
+   using ldbsearch at tconx time
+
+ - need a loadparm equivalent module that provides parameter defaults
+
+ - start smbd like this:  "smbd -C tdb://etc/samba/config.ldb" or
+   "smbd -C ldapi://var/run/ldapi"
+
+ - write a tool that generates a template ldap schema from an existing
+   ldb+tdb file
+
+ - no need to HUP smbd to reload config
+
+ - how to handle configuration comments? same problem as SWAT
+
+
+BUGS:
+  add a test case for last_entry_offset in trans2 find interfaces
+  conn refused
+  connect -> errno
+  no 137 resolution not possible
+  should not fallback to anon when pass supplied
+  should check pass-thu cap bit, and skip lots of tests
+  possibly allow the test suite to say "allow oversized replies" for
+     trans2 and other calls
+  handle servers that don't have the setattre call in torture
+  add max file coponent length test and max path len test
+  check for alloc failure in all core reply.c and trans2.c code where
+    allocation size depends on client parameter
+
+case-insenstive idea:
+  all filenames on disk lowercase
+  real case in extended attribute
+  keep cache of what dirs are all lowercase
+  when searching for name, don't search if dir is definately all lowercase
+  when creating file, use dnotify to tell if someone else creates at
+  same time
+
+solve del *.* idea:
+  make mangle cache dynamic size
+  fill during a dir scan
+  setup a timer
+  destroy cache after 30 sec
+  destroy if a 2nd dir scan happens on same dir
+